"http.cookies" --- HTTP state management
****************************************

**Code source :** Lib/http/cookies.py

======================================================================

The "http.cookies" module defines classes for abstracting the concept
of cookies, an HTTP state management mechanism. It supports both
simple string-only cookies, and provides an abstraction for having any
serializable data-type as cookie value.

The module formerly strictly applied the parsing rules described in
the **RFC 2109** and **RFC 2068** specifications.  It has since been
discovered that MSIE 3.0x didn't follow the character rules outlined
in those specs; many current-day browsers and servers have also
relaxed parsing rules when it comes to cookie handling.  As a result,
this module now uses parsing rules that are a bit less strict than
they once were.

The character set, "string.ascii_letters", "string.digits" and
"!#$%&'*+-.^_`|~:" denote the set of valid characters allowed by this
module in a cookie name (as "key").

Modifié dans la version 3.3: Allowed ':' as a valid cookie name
character.

Note:

  Quand un témoin invalide est rencontré, l'exception "CookieError"
  est levée. Si les données du témoin proviennent d'un navigateur il
  faut impérativement gérer les données invalides en attrapant
  "CookieError".

exception http.cookies.CookieError

   Exception levée pour cause d'incompatibilité avec la **RFC 2109**.
   Exemples : attributs incorrects, en-tête "Set-Cookie" incorrect,
   etc.

class http.cookies.BaseCookie([input])

   Cette classe définit un dictionnaire dont les clés sont des chaines
   de caractères et dont les valeurs sont des instances de "Morsel".
   Notez qu'à l'assignation d'une valeur à une clé, la valeur est
   transformée en "Morsel" contenant la clé et la valeur.

   Si l'argument *input* est donné, il est passé à la méthode
   "load()".

class http.cookies.SimpleCookie([input])

   This class derives from "BaseCookie" and overrides "value_decode()"
   and "value_encode()". "SimpleCookie" supports strings as cookie
   values. When setting the value, "SimpleCookie" calls the builtin
   "str()" to convert the value to a string. Values received from HTTP
   are kept as strings.

Voir aussi:

  Module "http.cookiejar"
     HTTP cookie handling for web *clients*.  The "http.cookiejar" and
     "http.cookies" modules do not depend on each other.

  **RFC 2109** - HTTP State Management Mechanism
     Spécification de gestion d'états implantée par ce module.


Objets *Cookie*
===============

BaseCookie.value_decode(val)

   Renvoie une paire "(real_value, coded_value)" depuis une
   représentation de chaine. "real_value" peut être de n’importe quel
   type. Cette méthode ne décode rien dans "BaseCookie" – elle existe
   pour être surchargée.

BaseCookie.value_encode(val)

   Renvoie une paire "(real_value, coded_value)". *val* peut être de
   n’importe quel type, mais "coded_value" est toujours converti en
   chaine de caractères. Cette méthode n’encode pas dans "BaseCookie"
   – elle existe pour être surchargée.

   Généralement, les méthodes "value_encode()" et "value_decode()"
   doivent être inverses l'une de l'autre, c'est-à-dire qu'en envoyant
   la sortie de l'un dans l'entrée de l'autre la valeur finale doit
   être égale à la valeur initiale.

BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')

   Return a string representation suitable to be sent as HTTP headers.
   *attrs* and *header* are sent to each "Morsel"'s "output()" method.
   *sep* is used to join the headers together, and is by default the
   combination "'\r\n'" (CRLF).

BaseCookie.js_output(attrs=None)

   Renvoie un extrait de code JavaScript qui, lorsque exécuté par un
   navigateur qui supporte le JavaScript, va fonctionner de la même
   manière que si les en-têtes HTTP avaient été envoyés.

   *attrs* a la même signification que dans la méthode "output()".

   Deprecated since version 3.15, will be removed in version 3.19:
   This method generates a JavaScript snippet to set cookies in the
   browser, which is no longer considered a standard or recommended
   approach. Use "output()" instead to generate HTTP headers.

BaseCookie.load(rawdata)

   Si *rawdata* est une chaine de caractères, l'analyser comme étant
   un "HTTP_COOKIE" et ajouter les valeurs trouvées en tant que
   "Morsel"s. S'il s'agit d'un dictionnaire, cela est équivalent à :

      for k, v in rawdata.items():
          cookie[k] = v


Objets *Morsel*
===============

class http.cookies.Morsel

   Abstraction de paire clé / valeur, accompagnée d'attributs
   provenant de la spécification **RFC 2109**.

   Morsels are dictionary-like objects, whose set of keys is constant
   --- the valid **RFC 2109** attributes, which are:

      expires
      path
      comment
      domain
      max-age
      secure
      version
      httponly
      samesite
      partitioned

   L'attribut "httponly" spécifie que le témoin transféré dans les
   requêtes HTTP n'est pas accessible par le biais de JavaScript. Il
   s'agit d'une contre-mesure à certaines attaques de scripts inter-
   sites (*XSS*).

   The attribute "samesite" controls when the browser sends the cookie
   with cross-site requests. This helps to mitigate CSRF attacks.
   Valid values are "Strict" (only sent with same-site requests),
   "Lax" (sent with same-site requests and top-level navigations), and
   "None" (sent with same-site and cross-site requests). When using
   "None", the "secure" attribute must also be set, as required by
   modern browsers.

   The attribute "partitioned" indicates to user agents that these
   cross-site cookies *should* only be available in the same top-level
   context that the cookie was first set in. For this to be accepted
   by the user agent, you **must** also set "Secure".

   In addition, it is recommended to use the "__Host" prefix when
   setting partitioned cookies to make them bound to the hostname and
   not the registrable domain. Read CHIPS (Cookies Having Independent
   Partitioned State) for full details and examples.

   Les clés ne sont pas sensibles à la casse, leur valeur par défaut
   est "''".

   Modifié dans la version 3.5: "__eq__()" now takes "key" and "value"
   into account.

   Modifié dans la version 3.7: les attributs "key", "value" et
   "coded_value" sont en lecture seule. Utilisez "set()" pour les
   assigner.

   Modifié dans la version 3.8: ajout de la prise en charge de
   l'attribut "samesite".

   Modifié dans la version 3.14: Added support for the "partitioned"
   attribute.

Morsel.value

   La valeur du témoin.

Morsel.coded_value

   La valeur codée du témoin. C'est celle qui doit être transférée.

Morsel.key

   Le nom du témoin.

Morsel.set(key, value, coded_value)

   Assigne les attributs *key*, *value* et *coded_value*.

Morsel.isReservedKey(K)

   Renvoie si *K* est membre des clés d'un "Morsel".

Morsel.output(attrs=None, header='Set-Cookie:')

   Renvoie une représentation textuelle du *Morsel* compatible avec
   les en-têtes HTTP. Par défaut, tous les attributs sont inclus, à
   moins que *attrs* ne soit renseigné. Dans ce cas la valeur doit
   être une liste d'attributs à utiliser. Par défaut, *header* a la
   valeur ""Set-Cookie:"".

Morsel.js_output(attrs=None)

   Renvoie un extrait de code JavaScript qui, lorsque exécuté par un
   navigateur qui supporte le JavaScript, va fonctionner de la même
   manière que si les en-têtes HTTP avaient été envoyés.

   *attrs* a la même signification que dans la méthode "output()".

   Deprecated since version 3.15, will be removed in version 3.19:
   This method generates a JavaScript snippet to set cookies in the
   browser, which is no longer considered a standard or recommended
   approach. Use "output()" instead to generate HTTP headers.

Morsel.OutputString(attrs=None)

   Renvoie une chaine de caractères représentant le *Morsel*, nettoyé
   de son contexte HTTP ou JavaScript.

   *attrs* a la même signification que dans la méthode "output()".

Morsel.update(values)

   Met à jour les valeurs du dictionnaire du *Morsel* avec les valeurs
   provenant du dictionnaire *values*.  Lève une erreur si une des
   clés n'est pas un attribut **RFC 2109** valide.

   Modifié dans la version 3.5: une erreur est levée pour les clés
   invalides.

Morsel.copy(value)

   Renvoie une copie superficielle de l'objet *Morsel*.

   Modifié dans la version 3.5: renvoie un objet *Morsel* au lieu d'un
   "dict".

Morsel.setdefault(key, value=None)

   Lève une erreur si la clé n'est pas un attribut **RFC 2109**
   valide, sinon fonctionne de la même manière que
   "dict.setdefault()".


Exemple
=======

The following example demonstrates how to use the "http.cookies"
module.

   >>> 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=;";')
   >>> print(C)
   Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=;"
   >>> 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
