"http.server" --- HTTP servers
******************************

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

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

Ce module définit des classes implémentant des serveurs HTTP.

Avertissement:

  "http.server" is not recommended for production. It only implements
  basic security checks.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See
Plateformes WebAssembly for more information.

Une des classes, "HTTPServer", est une sous-classe de
"socketserver.TCPServer". Elle crée une interface de connexion
(*socket* en anglais) avant de rester à l'écoute des messages reçus
sur celle-ci, les répartissant à un gestionnaire d'évènements
(*handler* en anglais). Le code pour créer et exécuter le serveur
ressemble à ceci :

   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)

   Cette classe hérite de la classe "TCPServer". Ses instances
   contiennent l'adresse du serveur dans les variables d'instance
   "server_name" et "server_port".Le serveur est accessible par le
   gestionnaire d'évènements, habituellement par le biais de sa
   variable d'instance "server".

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)

   Cette classe est identique à *HTTPServer* mais utilise des fils
   d'exécution afin de gérer les requêtes, et ce, par le biais de
   "ThreadingMixIn". Ceci est utile afin de gérer les pré-ouvertures
   des interfaces de connexion des navigateurs web, sur lesquelles
   "HTTPServer" attendrait de façon perpétuelle.

   Ajouté dans la version 3.7.

On doit passer un *RequestHandlerClass* lors de l'instanciation de
"HTTPServer" et de "ThreadingHTTPServer". Ce module fournit trois
variantes différentes :

class http.server.BaseHTTPRequestHandler(request, client_address, server)

   Cette classe est utilisée afin de gérer les requêtes HTTP arrivant
   au serveur. Elle ne peut pas répondre par elle-même à des requêtes
   HTTP ; cette méthode doit être surchargée dans les classes
   dérivées, par exemple *GET* ou *POST*. La classe
   "BaseHTTPRequestHandler" fournit plusieurs classes et variables
   d'instance, ainsi que des méthodes à utiliser par les sous-classes.

   The handler will parse the request and the headers, then call a
   method specific to the request type. The method name is constructed
   from the request. For example, for the request method "SPAM", the
   "do_SPAM()" method will be called with no arguments. All of the
   relevant information is stored in instance variables of the
   handler.  Subclasses should not need to override or extend the
   "__init__()" method.

   "BaseHTTPRequestHandler" a les variables d'instances suivantes :

   client_address

      Contient un *n*-uplet de la forme "(host, port)", faisant
      référence à l'adresse du client.

   server

      Contient l'instance du serveur.

   close_connection

      Booléen qui doit être défini avant que "handle_one_request()" ne
      termine son exécution, indiquant si on peut recevoir une autre
      requête ou si la connexion doit être fermée.

   requestline

      Contient la chaîne de caractères représentant la ligne de
      requête HTTP. La dénotation de fin de ligne *CRLF* est enlevée.
      Cet attribut doit être défini par "handle_one_request()". Dans
      le cas où aucune ligne de requête valide n'a été traitée, il
      doit prendre la valeur de la chaîne de caractères vide.

   command

      Contient la commande (le type de requête). Par exemple, "'GET'".

   path

      Contient le chemin de la requête. Si la composante de requête de
      l'URL est présente, alors "path" contient la requête. Selon la
      terminologie de **RFC 3986**, "path" inclut ici "hier-part" et
      la "query".

   request_version

      Contient la version de la requête, en chaîne de caractères. Par
      exemple, "'HTTP/1.0'".

   headers

      Holds an instance of the class specified by the "MessageClass"
      class variable. This instance parses and manages the headers in
      the HTTP request. The "parse_headers()" function from
      "http.client" is used to parse the headers and it requires that
      the HTTP request provide a valid **RFC 5322** style header.

   rfile

      An "io.BufferedIOBase" input stream, ready to read from the
      start of the optional input data.

   wfile

      Contains the output stream for writing a response back to the
      client. Proper adherence to the HTTP protocol must be used when
      writing to this stream in order to achieve successful
      interoperation with HTTP clients.

      Modifié dans la version 3.6: This is an "io.BufferedIOBase"
      stream.

   "BaseHTTPRequestHandler" has the following attributes:

   server_version

      Précise la version du logiciel du serveur. Vous pouvez la
      modifier. Le format utilisé est constitué de plusieurs chaînes
      de caractères séparées par des caractères d'espacement, où
      chaque chaîne prend la forme *nom[/version]*. Par exemple,
      "'BaseHTTP/0.2'".

   sys_version

      Contient la version système de Python, dans une forme pouvant
      être utilisée par la méthode "version_string" ainsi que par la
      variable de classe "server_version". Par exemple,
      "'Python/1.4'".

   error_message_format

      Définit une chaîne de caractères avec champs de formatage devant
      être utilisée par la méthode "send_error()" afin de construire
      une réponse d'erreur pour le client. Par défaut, la chaîne
      contient des variables provenant de l'attribut "responses" se
      basant sur le code de statut passé à "send_error()".

   error_content_type

      Définit l'en-tête HTTP Content-Type des réponses d'erreur
      envoyées au client. La valeur par défaut est "'text/html'".

   protocol_version

      Specifies the HTTP version to which the server is conformant. It
      is sent in responses to let the client know the server's
      communication capabilities for future requests. If set to
      "'HTTP/1.1'", the server will permit HTTP persistent
      connections; however, your server *must* then include an
      accurate "Content-Length" header (using "send_header()") in all
      of its responses to clients. For backwards compatibility, the
      setting defaults to "'HTTP/1.0'".

   MessageClass

      Définit une classe similaire à "email.message.Message"
      permettant l'analyse des en-têtes HTTP. Habituellement, cette
      valeur n'est pas modifiée, et prend par défaut la valeur de
      "http.client.HTTPMessage".

   responses

      Cet attribut contient une table de correspondance entre des
      codes d'erreurs dénotés par des entiers et des *n*-uplets
      contenant un message court et un message long. Par exemple,
      "{code: (shortmessage, longmessage)}". Habituellement, le
      message *shortmessage* correspond à la clé *message* d'une
      réponse d'erreur, alors que le message *longmessage* correspond
      à la clé *explain* de celle-ci. Il est utilisé par les méthodes
      "send_response_only()" et "send_error()".

   Une instance de la classe "BaseHTTPRequestHandler" contient les
   méthodes suivantes :

   handle()

      Calls "handle_one_request()" once (or, if persistent connections
      are enabled, multiple times) to handle incoming HTTP requests.
      You should never need to override it; instead, implement
      appropriate "do_*()" methods.

   handle_one_request()

      This method will parse and dispatch the request to the
      appropriate "do_*()" method.  You should never need to override
      it.

   handle_expect_100()

      When an HTTP/1.1 conformant 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".

      Ajouté dans la version 3.2.

   send_error(code, message=None, explain=None)

      Sends and logs a complete error reply to the client. The numeric
      *code* specifies the HTTP error code, with *message* as an
      optional, short, human readable description of the error.  The
      *explain* argument can be used to provide more detailed
      information about the error; it will be formatted using the
      "error_message_format" attribute and emitted, after a complete
      set of headers, as the response body.  The "responses" attribute
      holds the default values for *message* and *explain* that will
      be used if no value is provided; for unknown codes the default
      value for both is the string "???". The body will be empty if
      the method is HEAD or the response code is one of the following:
      "1*xx*", "204 No Content", "205 Reset Content", "304 Not
      Modified".

      Modifié dans la version 3.4: The error response includes a
      Content-Length header. Added the *explain* argument.

   send_response(code, message=None)

      Adds a response header to the headers buffer and logs the
      accepted request. The HTTP response line is written to the
      internal buffer, followed by *Server* and *Date* headers. The
      values for these two headers are picked up from the
      "version_string()" and "date_time_string()" methods,
      respectively. If the server does not intend to send any other
      headers using the "send_header()" method, then "send_response()"
      should be followed by an "end_headers()" call.

      Modifié dans la version 3.3: Headers are stored to an internal
      buffer and "end_headers()" needs to be called explicitly.

   send_header(keyword, value)

      Adds the HTTP header to an internal buffer which will be written
      to the output stream when either "end_headers()" or
      "flush_headers()" is invoked. *keyword* should specify the
      header keyword, with *value* specifying its value. Note that,
      after the send_header calls are done, "end_headers()" MUST BE
      called in order to complete the operation.

      Modifié dans la version 3.2: Headers are stored in an internal
      buffer.

   send_response_only(code, message=None)

      Sends the response header only, used for the purposes when "100
      Continue" response is sent by the server to the client. The
      headers not buffered and sent directly the output stream.If the
      *message* is not specified, the HTTP message corresponding the
      response *code*  is sent.

      Ajouté dans la version 3.2.

   end_headers()

      Adds a blank line (indicating the end of the HTTP headers in the
      response) to the headers buffer and calls "flush_headers()".

      Modifié dans la version 3.2: The buffered headers are written to
      the output stream.

   flush_headers()

      Finally send the headers to the output stream and flush the
      internal headers buffer.

      Ajouté dans la version 3.3.

   log_request(code='-', size='-')

      Logs an accepted (successful) request. *code* should specify the
      numeric HTTP code associated with the response. If a size of the
      response is available, then it should be passed as the *size*
      parameter.

   log_error(...)

      Logs an error when a request cannot be fulfilled. By default, it
      passes the message to "log_message()", so it takes the same
      arguments (*format* and additional values).

   log_message(format, ...)

      Logs an arbitrary message to "sys.stderr". This is typically
      overridden to create custom error logging mechanisms. The
      *format* argument is a standard printf-style format string,
      where the additional arguments to "log_message()" are applied as
      inputs to the formatting. The client ip address and current date
      and time are prefixed to every message logged.

   version_string()

      Returns the server software's version string. This is a
      combination of the "server_version" and "sys_version"
      attributes.

   date_time_string(timestamp=None)

      Returns the date and time given by *timestamp* (which must be
      "None" or in the format returned by "time.time()"), formatted
      for a message header. If *timestamp* is omitted, it uses the
      current date and time.

      The result looks like "'Sun, 06 Nov 1994 08:49:37 GMT'".

   log_date_time_string()

      Returns the current date and time, formatted for logging.

   address_string()

      Returns the client address.

      Modifié dans la version 3.3: Previously, a name lookup was
      performed. To avoid name resolution delays, it now always
      returns the IP address.

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.

   Modifié dans la version 3.7: Added the *directory* parameter.

   Modifié dans la version 3.9: The *directory* parameter accepts a
   *path-like object*.

   A lot of the work, such as parsing the request, is done by the base
   class "BaseHTTPRequestHandler".  This class implements the
   "do_GET()" and "do_HEAD()" functions.

   The following are defined as class-level attributes of
   "SimpleHTTPRequestHandler":

   server_version

      This will be ""SimpleHTTP/" + __version__", where "__version__"
      is defined at the module level.

   extensions_map

      A dictionary mapping suffixes into MIME types, contains custom
      overrides for the default system mappings. The mapping is used
      case-insensitively, and so should contain only lower-cased keys.

      Modifié dans la version 3.9: This dictionary is no longer filled
      with the default system mappings, but only contains overrides.

   The "SimpleHTTPRequestHandler" class defines the following methods:

   do_HEAD()

      This method serves the "'HEAD'" request type: it sends the
      headers it would send for the equivalent "GET" request. See the
      "do_GET()" method for a more complete explanation of the
      possible headers.

   do_GET()

      The request is mapped to a local file by interpreting the
      request as a path relative to the current working directory.

      If the request was mapped to a directory, the directory is
      checked for a file named "index.html" or "index.htm" (in that
      order). If found, the file's contents are returned; otherwise a
      directory listing is generated by calling the "list_directory()"
      method. This method uses "os.listdir()" to scan the directory,
      and returns a "404" error response if the "listdir()" fails.

      If the request was mapped to a file, it is opened. Any "OSError"
      exception in opening the requested file is mapped to a "404",
      "'File not found'" error. If there was an "'If-Modified-Since'"
      header in the request, and the file was not modified after this
      time, a "304", "'Not Modified'" response is sent. Otherwise, the
      content type is guessed by calling the "guess_type()" method,
      which in turn uses the *extensions_map* variable, and the file
      contents are returned.

      A "'Content-type:'" header with the guessed content type is
      output, followed by a "'Content-Length:'" header with the file's
      size and a "'Last-Modified:'" header with the file's
      modification time.

      Then follows a blank line signifying the end of the headers, and
      then the contents of the file are output.

      For example usage, see the implementation of the "test" function
      in Lib/http/server.py.

      Modifié dans la version 3.7: Support of the "'If-Modified-
      Since'" header.

The "SimpleHTTPRequestHandler" class can be used in the following
manner in order to create a very basic webserver serving files
relative to the current directory:

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

"SimpleHTTPRequestHandler" can also be subclassed to enhance behavior,
such as using different index file names by overriding the class
attribute "index_pages".

class http.server.CGIHTTPRequestHandler(request, client_address, server)

   This class is used to serve either files or output of CGI scripts
   from the current directory and below. Note that mapping HTTP
   hierarchic structure to local directory structure is exactly as in
   "SimpleHTTPRequestHandler".

   Note:

     CGI scripts run by the "CGIHTTPRequestHandler" class cannot
     execute redirects (HTTP code 302), because code 200 (script
     output follows) is sent prior to execution of the CGI script.
     This pre-empts the status code.

   The class will however, run the CGI script, instead of serving it
   as a file, if it guesses it to be a CGI script.  Only directory-
   based CGI are used --- the other common server configuration is to
   treat special extensions as denoting CGI scripts.

   The "do_GET()" and "do_HEAD()" functions are modified to run CGI
   scripts and serve the output, instead of serving files, if the
   request leads to somewhere below the "cgi_directories" path.

   The "CGIHTTPRequestHandler" defines the following data member:

   cgi_directories

      This defaults to "['/cgi-bin', '/htbin']" and describes
      directories to treat as containing CGI scripts.

   The "CGIHTTPRequestHandler" defines the following method:

   do_POST()

      This method serves the "'POST'" request type, only allowed for
      CGI scripts.  Error 501, "Can only POST to CGI scripts", is
      output when trying to POST to a non-CGI url.

   Note that CGI scripts will be run with UID of user nobody, for
   security reasons.  Problems with the CGI script will be translated
   to error 403.

   Deprecated since version 3.13, will be removed in version 3.15:
   "CGIHTTPRequestHandler" is being removed in 3.15.  CGI has not been
   considered a good way to do things for well over a decade. This
   code has been unmaintained for a while now and sees very little
   practical use. Retaining it could lead to further security
   considerations.


Command-line interface
======================

"http.server" can also be invoked directly using the "-m" switch of
the interpreter.  The following example illustrates how to serve files
relative to the current directory:

   python -m http.server [OPTIONS] [port]

The following options are accepted:

port

   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

-b, --bind <address>

   Specifies a specific address to which it should bind. Both IPv4 and
   IPv6 addresses are supported. By default, the server binds itself
   to all interfaces. For example, the following command causes the
   server to bind to localhost only:

      python -m http.server --bind 127.0.0.1

   Ajouté dans la version 3.4.

   Modifié dans la version 3.8: Support IPv6 in the "--bind" option.

-d, --directory <dir>

   Specifies a directory to which it should serve the files. By
   default, the server uses the current directory. For example, the
   following command uses a specific directory:

      python -m http.server --directory /tmp/

   Ajouté dans la version 3.7.

-p, --protocol <version>

   Specifies the HTTP version to which the server is conformant. By
   default, the server is conformant to HTTP/1.0. For example, the
   following command runs an HTTP/1.1 conformant server:

      python -m http.server --protocol HTTP/1.1

   Ajouté dans la version 3.11.

--cgi

   "CGIHTTPRequestHandler" can be enabled in the command line by
   passing the "--cgi" option:

      python -m http.server --cgi

   Deprecated since version 3.13, will be removed in version 3.15:
   "http.server" command line "--cgi" support is being removed because
   "CGIHTTPRequestHandler" is being removed.

Avertissement:

  "CGIHTTPRequestHandler" and the "--cgi" command-line option are not
  intended for use by untrusted clients and may be vulnerable to
  exploitation. Always use within a secure environment.


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.

Modifié dans la version 3.12: Control characters are scrubbed in
stderr logs.
