"http.cookies" --- Gestión del estado HTTP
******************************************

**Source code:** 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** y **RFC 2068**. 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 **RFC 2109** invalidity: 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** - 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
   "Morsel"s. 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**.

   Los Morsels son objetos similares a diccionarios, cuyo conjunto de
   claves es constante --- los atributos válidos **RFC 2109**, 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**.

   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**;
   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
