urllib.parse — Parse URLs into components

Código fuente: 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».

The module has been designed to match the internet RFC on Relative Uniform Resource Locators. It supports the following URL schemes: file, ftp, gopher, hdl, http, https, imap, itms-services, mailto, mms, news, nntp, prospero, rsync, rtsp, rtsps, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

Detalles de implementación de CPython: The inclusion of the itms-services URL scheme can prevent an app from passing Apple’s App Store review process for the macOS and iOS App Stores. Handling for the itms-services scheme is always removed on iOS; on macOS, it may be removed if CPython has been built with the --with-app-store-compliance option.

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.

This module’s functions use the deprecated term netloc (or net_loc), which was introduced in RFC 1808. However, this term has been obsoleted by RFC 3986, which introduced the term authority as its replacement. The use of netloc is continued for backward compatibility.

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=None, allow_fragments=True, *, missing_as_none=False)

Parse a URL into six components, returning a 6-item named tuple. This corresponds to the general structure of a URL: scheme://netloc/path;parameters?query#fragment. Each tuple item is a string, possibly empty, or None if missing_as_none is true. Not defined component are represented an empty string (by default) or None if missing_as_none is true. The components are not broken up into smaller parts (for example, the network location is a single string), and % escapes are not expanded. The delimiters as shown above are not part of the result, except for a leading slash in the path component, which is retained if present. For example:

>>> 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'
>>> urlparse("http://docs.python.org?")
ParseResult(scheme='http', netloc='docs.python.org',
            path='', params='', query='', fragment='')
>>> urlparse("http://docs.python.org?", missing_as_none=True)
ParseResult(scheme='http', netloc='docs.python.org',
            path='', params=None, query='', fragment=None)

Siguiendo las especificaciones de sintaxis en RFC 1808, 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='')
>>> urlparse('help/Python.html', missing_as_none=True)
ParseResult(scheme=None, netloc=None, path='help/Python.html',
            params=None, query=None, fragment=None)

The scheme argument gives the default addressing scheme, to be used only if the URL does not specify one. It should be the same type (text or bytes) as urlstring or None, except that the '' is always allowed, and is automatically converted to b'' if appropriate.

If the allow_fragments argument is false, fragment identifiers are not recognized. Instead, they are parsed as part of the path, parameters or query component, and fragment is set to None or the empty string (depending on the value of missing_as_none) in the return value.

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	scheme parameter or empty string [1]
netloc	1	Parte de ubicación de red	None or empty string [1]
path	2	Hierarchical path	cadena vacía
params	3	Parámetros para el último elemento de ruta de acceso	None or empty string [1]
query	4	Componente de consulta	None or empty string [1]
fragment	5	Identificador de fragmento	None or empty string [1]
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

[1] (1,2,3,4,5,6)

Depending on the value of the missing_as_none argument.

La lectura del atributo port lanzará 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 lanzará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() no realiza validaciones. Mire URL parsing security para más información.

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: The fragment is now parsed for all URL schemes (unless allow_fragments is false), in accordance with RFC 3986. Previously, an allowlist of schemes that support fragments existed.

Distinto en la versión 3.6: Out-of-range port numbers now raise ValueError, instead of returning None.

Distinto en la versión 3.8: Los caracteres que afectan al análisis de netloc en la normalización de NFKC ahora lanzarán ValueError.

Distinto en la versión 3.15.0a5 (unreleased): Added the missing_as_none parameter.

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.10: Añadido parámetro separator con un valor por defecto de &. Versiones de Python anterior a Python 3.10 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 & el separador por defecto.

Obsoleto desde la versión 3.14: Accepting objects with false values (like 0 and []) except empty strings and byte-like objects and None is now deprecated.

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.10: Añadido parámetro separator con un valor por defecto de &. Versiones de Python anterior a Python 3.10 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 & el separador por defecto.

urllib.parse.urlunparse(parts)

urllib.parse.urlunparse(parts, *, keep_empty)

Construct a URL from a tuple as returned by urlparse(). The parts argument can be any six-item iterable.

This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent).

If keep_empty is true, empty strings are kept in the result (for example, a ? for an empty query), only None components are omitted. This allows rebuilding a URL that was parsed with option missing_as_none=True. By default, keep_empty is true if parts is the result of the urlparse() call with missing_as_none=True.

Distinto en la versión 3.15.0a5 (unreleased): Added the keep_empty parameter.

urllib.parse.urlsplit(urlstring, scheme=None, allow_fragments=True, *, missing_as_none=False)

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). 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	scheme parameter or empty string [1]
netloc	1	Parte de ubicación de red	None or empty string [2]
path	2	Hierarchical path	cadena vacía
query	3	Componente de consulta	None or empty string [2]
fragment	4	Identificador de fragmento	None or empty string [2]
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

[2] (1,2,3)

Depending on the value of the missing_as_none argument.

La lectura del atributo port lanzará 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 lanzará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.

Siguiendo algunas de las WHATWG spec que actualizan el RFC 3986, los caracteres de control C0 y de espacio se eliminan de la URL. Los caracteres \n, \r y tab \t se eliminan de la URL en cualquier posición.

Advertencia

urlsplit() no realiza validaciones. Mire URL parsing security para más información.

Distinto en la versión 3.6: Out-of-range port numbers now raise ValueError, instead of returning None.

Distinto en la versión 3.8: Los caracteres que afectan al análisis de netloc en la normalización de NFKC ahora lanzarán ValueError.

Distinto en la versión 3.10: Los caracteres ASCII de nueva línea y tab se eliminan de la URL.

Distinto en la versión 3.12: Los caracteres de control WHATWG C0 y de espacio se eliminan de la URL.

Distinto en la versión 3.15.0a5 (unreleased): Added the missing_as_none parameter.

urllib.parse.urlunsplit(parts)

urllib.parse.urlunsplit(parts, *, keep_empty)

Combine the elements of a tuple as returned by urlsplit() into a complete URL as a string. The parts argument can be any five-item iterable.

This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent).

If keep_empty is true, empty strings are kept in the result (for example, a ? for an empty query), only None components are omitted. This allows rebuilding a URL that was parsed with option missing_as_none=True. By default, keep_empty is true if parts is the result of the urlsplit() call with missing_as_none=True.

Distinto en la versión 3.15.0a5 (unreleased): Added the keep_empty parameter.

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.

Advertencia

Because an absolute URL may be passed as the url parameter, it is generally not secure to use urljoin with an attacker-controlled url. For example in, urljoin("https://website.com/users/", username), if username can contain an absolute URL, the result of urljoin will be the absolute URL.

Distinto en la versión 3.5: Comportamiento actualizado para coincidir con la semántica definida en RFC 3986.

urllib.parse.urldefrag(url, *, missing_as_none=False)

If url contains a fragment identifier, return a modified version of url with no fragment identifier, and the fragment identifier as a separate string. If there is no fragment identifier in url, return url unmodified and an empty string (by default) or None if missing_as_none is true.

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	None or empty string [3]

[3]

Depending on the value of the missing_as_none argument.

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.

Distinto en la versión 3.15.0a5 (unreleased): Added the missing_as_none parameter.

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.

Análisis de seguridad de URL

Las APIs urlsplit() y urlparse() no realizan validación de las entradas. Es posible que no produzcan errores en entradas que otras aplicaciones consideren inválidas. También pueden tener éxito en algunas entradas que podrían no ser consideradas URLs en otros lugares. Su propósito es más la funcionalidad práctica que la pureza.

Instead of raising an exception on unusual input, they may instead return some component parts as empty strings or None (depending on the value of the missing_as_none argument). Or components may contain more than perhaps they should.

Se recomienda que los usuarios de estas APIs, en las que los valores se pueden usar en cualquier lugar con implicaciones de seguridad, codifiquen de forma defensiva. Realicen algunas comprobaciones en su código antes de confiar en un componente devuelto. ¿Tiene sentido ese scheme? ¿Es ese path sensible? ¿Hay algo extraño en ese hostname? etc.

Lo que constituye una URL no está universalmente bien definido. Aplicaciones diferentes tienen diferentes necesidades y restricciones deseadas. Por ejemplo, la WHATWG spec describe lo que requieren los clientes web orientados al usuario, como un navegador web. Mientras RFC 3986 es más general. Estas funciones incorporan algunos aspectos de ambos, pero no se puede afirmar que cumpla con ninguno de los dos. Las API y el código de usuario existente con expectativas sobre comportamientos específicos son anteriores a ambos estándares, lo que nos lleva a ser muy cautelosos realizando cambios en el comportamiento de la API.

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()

Return the re-combined version of the original URL as a string. This may differ from the original URL in that the scheme may be normalized to lower case and empty components may be dropped. Specifically, empty parameters, queries, and fragment identifiers will be removed unless the URL was parsed with missing_as_none=True.

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/'
>>> r3 = urlsplit(url, missing_as_none=True)
>>> r3.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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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 a RFC 3986 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.

Distinto en la versión 3.5: Added the quote_via parameter.

Obsoleto desde la versión 3.14: Accepting objects with false values (like 0 and []) except empty strings and byte-like objects and None is now deprecated.

Ver también

WHATWG - URL estándar actual

Grupo de trabajo para el estándar URL que define URLs, dominio, dirección IP, formato application/x-www-form-urlencoded y su API.

RFC 3986 - 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 - Formato de direcciones IPv6 literales en URL.

Esto especifica los requisitos de análisis de las direcciones URL IPv6.

RFC 2396 - 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 - El esquema mailto URL.

Análisis de requisitos para esquemas de URL de correo a correo.

RFC 1808 - 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 - Localizadores uniformes de recursos (URL)

Esto especifica la sintaxis formal y la semántica de las direcciones URL absolutas.