# `urllib.parse` — Analiza URL en componentes

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

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)

  Analice una dirección URL en seis componentes y retorne una tupla de 6 elementos named tuple. 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 escapes 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
      >>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
      >>> o
      ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> o.scheme
      'http'
      >>> o.port
      80
      >>> o.geturl()
      'http://www.cwi.nl:80/%7Eguido/Python.html'

  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='')

  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='')

  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 false), de acuerdo con RFC 3986. 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 true indica que los espacios en blanco deben conservarse como cadenas en blanco. El valor false 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 false (valor predeterminado), los errores se omiten silenciosamente. Si es true, 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.

  The optional argument separator is the symbol to use for separating the query arguments. It defaults to `&`.

  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.8.8: Added separator parameter with the default value of `&`. Python versions earlier than Python 3.8.8 allowed using both `;` and `&` as query parameter separator. This has been changed to allow only a single separator key, with `&` as the default separator.

`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 true indica que los espacios en blanco deben conservarse como cadenas en blanco. El valor false 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 false (valor predeterminado), los errores se omiten silenciosamente. Si es true, 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.

  The optional argument separator is the symbol to use for separating the query arguments. It defaults to `&`.

  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.8.8: Added separator parameter with the default value of `&`. Python versions earlier than Python 3.8.8 allowed using both `;` and `&` as query parameter separator. This has been changed to allow only a single separator key, with `&` as the default separator.

`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). 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 the WHATWG spec that updates RFC 3986, ASCII newline `\n`, `\r` and tab `\t` characters are stripped from the URL.

  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.8.10: ASCII newline and tab 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, a partir de `//` 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 que coincida con la semántica definida en RFC 3986.

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

  Extract the url from a wrapped URL (that is, a string formatted as `<URL:scheme://host/path>`, `<scheme://host/path>`, `URL:scheme://host/path` or `scheme://host/path`). If url is not a wrapped URL, it is returned without changes.

## 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 descodificació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)

  Reemplace caracteres especiales en string con el 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 `str` o `bytes`.

  Distinto en la versión 3.7: Moved from RFC 2396 to RFC 3986 for quoting URL strings. «~» is now included in the set of unreserved characters.

  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 reemplace los espacios por signos más, según sea necesario para citar valores de formulario HTML al crear una cadena de consulta para ir a una dirección URL. Además, los signos de la cadena original se escapan a menos que se incluyan en safe. Tampoco tiene safe predeterminado para `'/'`.

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

  Reemplace los escapes `%xx` por su equivalente de un solo carácter. 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()`.

  string debe ser `str`.

  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/'`.

`urllib.parse.``unquote_plus`(string, encoding='utf-8', errors='replace')

  Como `unquote()`, pero también reemplace los signos más por espacios, según sea necesario para los valores de formulario HTML sin comillas.

  string debe ser `str`.

  Ejemplo: `unquote_plus('/El+Ni%C3%B1o/')` produce `'/El Niño/'`.

`urllib.parse.``unquote_to_bytes`(string)

  Reemplace los escapes `%xx` por su equivalente de un solo octeto y retorne un objeto `bytes`.

  string puede ser `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 elemento value 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 urlencode para generar una cadena de consulta para una dirección URL o datos para POST.</urllib-examples>

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