"xmlrpc.server" --- Servidores XML-RPC básicos
**********************************************

**Código-fonte:** Lib/xmlrpc/server.py

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

The "xmlrpc.server" module provides a basic server framework for XML-
RPC servers written in Python.  Servers can either be free standing,
using "SimpleXMLRPCServer", or embedded in a CGI environment, using
"CGIXMLRPCRequestHandler".

Aviso:

  The "xmlrpc.server" module is not secure against maliciously
  constructed data.  If you need to parse untrusted or unauthenticated
  data, see Segurança no XML.

Disponibilidade: not WASI.

Este módulo não funciona ou não está disponível em WebAssembly. Veja
Plataformas WebAssembly para mais informações.

class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)

   Cria uma nova instância do servidor. Esta classe fornece métodos
   para registro de funções que podem ser chamadas pelo protocolo XML-
   RPC. O parâmetro *requestHandler* deve ser uma fábrica para
   instâncias do tratador de solicitações; o padrão é
   "SimpleXMLRPCRequestHandler". Os parâmetros *addr* e
   *requestHandler* são passados para o construtor
   "socketserver.TCPServer". Se *logRequests* for true (o padrão), as
   solicitações serão registradas; definir esse parâmetro como false
   desativará os registros. Os parâmetros *allow_none* e *encoding*
   são transmitidos para "xmlrpc.client" e controlam as respostas XML-
   RPC que serão retornadas do servidor. O parâmetro
   *bind_and_activate* controla se "server_bind()" e
   "server_activate()" são chamados imediatamente pelo construtor; o
   padrão é true. A configuração como false permite que o código
   manipule a variável de classe *allow_reuse_address* antes que o
   endereço seja vinculado. O parâmetro *use_builtin_types* é passado
   para a função "loads()" e controla quais tipos são processados
   quando valores de data/hora ou dados binários são recebidos; o
   padrão é false.

   Alterado na versão 3.3: O sinalizador *use_builtin_types* foi
   adicionado.

class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)

   Cria uma nova instância para manipular solicitações XML-RPC em um
   ambiente CGI. Os parâmetros *allow_none* e *encoding* são
   transmitidos para "xmlrpc.client" e controlam as respostas XML-RPC
   que serão retornadas do servidor. O parâmetro *use_builtin_types* é
   passado para a função "loads()" e controla quais tipos são
   processados quando valores de data/hora ou dados binários são
   recebidos; o padrão é false.

   Alterado na versão 3.3: O sinalizador *use_builtin_types* foi
   adicionado.

class xmlrpc.server.SimpleXMLRPCRequestHandler

   Cria uma nova instância do manipulador de solicitações. Este
   manipulador de solicitação possui suporte a solicitações "POST" e
   modifica o registro para que o parâmetro *logRequests* para o
   construtor de "SimpleXMLRPCServer" seja respeitado.


SimpleXMLRPCServer objects
==========================

A classe "SimpleXMLRPCServer" é baseada em "socketserver.TCPServer" e
fornece um meio de criar servidores XML-RPC simples e independentes.

SimpleXMLRPCServer.register_function(function=None, name=None)

   Registra uma função que possa responder às solicitações XML-RPC. Se
   *name* for fornecido, será o nome do método associado a *function*,
   caso contrário, "function.__name__" será usado. *name* é uma string
   e pode conter caracteres ilegais para identificadores Python,
   incluindo o caractere de ponto.

   Este método também pode ser usado como um decorador. Quando usado
   como decorador, *name* só pode ser fornecido como argumento nomeado
   para registrar *function* em *name*. Se nenhum *name* for
   fornecido, "function.__name__" será usado.

   Alterado na versão 3.7: "register_function()" pode ser usado como
   um decorador.

SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)

   Registra um objeto que é usado para expor nomes de métodos que não
   foram registrados usando "register_function()". Se *instance*
   contiver um método "_dispatch()", ele será chamado com o nome do
   método solicitado e os parâmetros da solicitação. Sua API é "def
   _dispatch(self, method, params)" (observe que *params* não
   representa uma lista de argumentos variáveis). Se ele chama uma
   função subjacente para executar sua tarefa, essa função é chamada
   como "func(*params)", expandindo a lista de parâmetros. O valor de
   retorno de "_dispatch()" é retornado ao cliente como resultado. Se
   *instance* não possui o método "_dispatch()", é procurado por um
   atributo correspondente ao nome do método solicitado.

   Se o argumento opcional *allow_dotted_names* for true e a instância
   não tiver o método "_dispatch()", e se o nome do método solicitado
   contiver pontos, cada componente do nome do método será pesquisado
   individualmente, com o efeito de que um simples pesquisa
   hierárquica é realizada. O valor encontrado nessa pesquisa é
   chamado com os parâmetros da solicitação e o valor retornado é
   passado de volta ao cliente.

   Aviso:

     A ativação da opção *allow_dotted_names* permite que os invasores
     acessem as variáveis globais do seu módulo e podem permitir que
     os invasores executem códigos arbitrários em sua máquina. Use
     esta opção apenas em uma rede fechada e segura.

SimpleXMLRPCServer.register_introspection_functions()

   Registra as funções de introspecção XML-RPC "system.listMethods",
   "system.methodHelp" e "system.methodSignature".

SimpleXMLRPCServer.register_multicall_functions()

   Registra a função de multichamada XML-RPC system.multicall.

SimpleXMLRPCRequestHandler.rpc_paths

   Um valor de atributo que deve ser uma tupla listando partes do
   caminho válidas da URL para receber solicitações XML-RPC.
   Solicitações postadas em outros caminhos resultarão em um erro HTTP
   404 "página inexistente". Se esta tupla estiver vazia, todos os
   caminhos serão considerados válidos. O valor padrão é "('/',
   '/RPC2')".


SimpleXMLRPCServer example
--------------------------

Código do servidor:

   from xmlrpc.server import SimpleXMLRPCServer
   from xmlrpc.server import SimpleXMLRPCRequestHandler

   # Restringe a um caminho em particular.
   class RequestHandler(SimpleXMLRPCRequestHandler):
       rpc_paths = ('/RPC2',)

   # Cria o servidor
   with SimpleXMLRPCServer(('localhost', 8000),
                           requestHandler=RequestHandler) as server:
       server.register_introspection_functions()

       # Registra uma função pow(); isso vai usar o valor de
       # pow.__name__ como o nome, que é apenas 'pow'.
       server.register_function(pow)

       # Registra uma função sob um nome diferente
       def adder_function(x, y):
           return x + y
       server.register_function(adder_function, 'add')

       # Registra uma instância; todos os métodos da instância
       # são publicados como métodos XML-RPC (neste caso,
       # apenas 'mul').
       class MyFuncs:
           def mul(self, x, y):
               return x * y

       server.register_instance(MyFuncs())

       # Executa o laço principal do servidor
       server.serve_forever()

O código do cliente a seguir chamará os métodos disponibilizados pelo
servidor anterior:

   import xmlrpc.client

   s = xmlrpc.client.ServerProxy('http://localhost:8000')
   print(s.pow(2,3))  # Returns 2**3 = 8
   print(s.add(2,3))  # Returns 5
   print(s.mul(5,2))  # Returns 5*2 = 10

   # Exibe uma lista dos métodos disponíveis
   print(s.system.listMethods())

"register_function()" também pode ser usado como um decorador. O
exemplo anterior do servidor pode registrar funções com um decorador:

   from xmlrpc.server import SimpleXMLRPCServer
   from xmlrpc.server import SimpleXMLRPCRequestHandler

   class RequestHandler(SimpleXMLRPCRequestHandler):
       rpc_paths = ('/RPC2',)

   with SimpleXMLRPCServer(('localhost', 8000),
                           requestHandler=RequestHandler) as server:
       server.register_introspection_functions()

       # Registra a função pow(); isso vai usar o valor de
       # pow.__name__ como o nome, que é apenas 'pow'.
       server.register_function(pow)

       # Registra uma função sob um nome diferente, usando
       # register_function como um decorador. *name* só pode
       # ser dado como um argumento nomeado.
       @server.register_function(name='add')
       def adder_function(x, y):
           return x + y

       # Registra uma função sob function.__name__.
       @server.register_function
       def mul(x, y):
           return x * y

       server.serve_forever()

O exemplo a seguir, incluído no módulo "Lib/xmlrpc/server.py", mostra
um servidor que permite nomes com pontos e registra uma função de
várias chamadas.

Aviso:

  Enabling the *allow_dotted_names* option allows intruders to access
  your module's global variables and may allow intruders to execute
  arbitrary code on your machine.  Only use this example within a
  secure, closed network.

   import datetime as dt

   class ExampleService:
       def getData(self):
           return '42'

       class currentTime:
           @staticmethod
           def getCurrentTime():
               return dt.datetime.now()

   with SimpleXMLRPCServer(("localhost", 8000)) as server:
       server.register_function(pow)
       server.register_function(lambda x,y: x+y, 'add')
       server.register_instance(ExampleService(), allow_dotted_names=True)
       server.register_multicall_functions()
       print('Serving XML-RPC on localhost port 8000')
       try:
           server.serve_forever()
       except KeyboardInterrupt:
           print("\nKeyboard interrupt received, exiting.")
           sys.exit(0)

Esta demonstração ExampleService pode ser chamada na linha de comando:

   python -m xmlrpc.server

O cliente que interage com o servidor acima está incluído em
"Lib/xmlrpc/client.py":

   server = ServerProxy("http://localhost:8000")

   try:
       print(server.currentTime.getCurrentTime())
   except Error as v:
       print("ERROR", v)

   multi = MultiCall(server)
   multi.getData()
   multi.pow(2,9)
   multi.add(1,2)
   try:
       for response in multi():
           print(response)
   except Error as v:
       print("ERROR", v)

Este cliente que interage com o servidor XMLRPC de demonstração pode
ser chamado como:

   python -m xmlrpc.client


CGIXMLRPCRequestHandler
=======================

A classe "CGIXMLRPCRequestHandler" pode ser usada para manipular
solicitações XML-RPC enviadas para scripts CGI Python.

CGIXMLRPCRequestHandler.register_function(function=None, name=None)

   Registra uma função que possa responder às solicitações XML-RPC. Se
   *name* for fornecido, será o nome do método associado a *function*,
   caso contrário, "function.__name__" será usado. *name* é uma string
   e pode conter caracteres ilegais para identificadores Python,
   incluindo o caractere de ponto.

   Este método também pode ser usado como um decorador. Quando usado
   como decorador, *name* só pode ser fornecido como argumento nomeado
   para registrar *function* em *name*. Se nenhum *name* for
   fornecido, "function.__name__" será usado.

   Alterado na versão 3.7: "register_function()" pode ser usado como
   um decorador.

CGIXMLRPCRequestHandler.register_instance(instance)

   Registra um objeto que é usado para expor nomes de métodos que não
   foram registrados usando "register_function()". Se a instância
   contiver um método "_dispatch()", ela será chamada com o nome do
   método solicitado e os parâmetros da solicitação; o valor retornado
   é retornado ao cliente como resultado. Se a instância não tiver um
   método "_dispatch()", será procurado um atributo correspondente ao
   nome do método solicitado; se o nome do método solicitado contiver
   pontos, cada componente do nome do método será pesquisado
   individualmente, com o efeito de que uma pesquisa hierárquica
   simples é executada. O valor encontrado nessa pesquisa é chamado
   com os parâmetros da solicitação e o valor retornado é passado de
   volta ao cliente.

CGIXMLRPCRequestHandler.register_introspection_functions()

   Registra as funções de introspecção XML-RPC "system.listMethods",
   "system.methodHelp" e "system.methodSignature".

CGIXMLRPCRequestHandler.register_multicall_functions()

   Registra a função de multichamada XML-RPC "system.multicall".

CGIXMLRPCRequestHandler.handle_request(request_text=None)

   Manipula uma solicitação XML-RPC. Se *request_text* for fornecido,
   devem ser os dados POST fornecidos pelo servidor HTTP, caso
   contrário, o conteúdo do stdin será usado.

Exemplo:

   class MyFuncs:
       def mul(self, x, y):
           return x * y


   handler = CGIXMLRPCRequestHandler()
   handler.register_function(pow)
   handler.register_function(lambda x,y: x+y, 'add')
   handler.register_introspection_functions()
   handler.register_instance(MyFuncs())
   handler.handle_request()


Documentando servidor XMLRPC
============================

Essas classes estendem as classes acima para servir a documentação
HTML em resposta a solicitações HTTP GET. Os servidores podem ser
independentes, usando "DocXMLRPCServer" ou incorporados em um ambiente
CGI, usando "DocCGIXMLRPCRequestHandler".

class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)

   Cria uma nova instância do servidor. Todos os parâmetros têm o
   mesmo significado que para "SimpleXMLRPCServer"; *requestHandler*
   assume como padrão "DocXMLRPCRequestHandler".

   Alterado na versão 3.3: O sinalizador *use_builtin_types* foi
   adicionado.

class xmlrpc.server.DocCGIXMLRPCRequestHandler

   Cria uma nova instância para manipular solicitações XML-RPC em um
   ambiente CGI.

class xmlrpc.server.DocXMLRPCRequestHandler

   Cria uma nova instância do manipulador de solicitações. Este
   manipulador de solicitações possui suporte a solicitações POST de
   XML-RPC, documenta solicitações GET e modifica o registro para que
   o parâmetro *logRequests* no parâmetro "DocXMLRPCServer" seja
   respeitado.


DocXMLRPCServer objects
=======================

A classe "DocXMLRPCServer" é derivada de "SimpleXMLRPCServer" e
fornece um meio de criar servidores XML-RPC autodocumentados e
independentes. Solicitações HTTP POST são tratadas como chamadas de
método XML-RPC. As solicitações HTTP GET são tratadas gerando
documentação HTML no estilo pydoc. Isso permite que um servidor
forneça sua própria documentação baseada na Web.

DocXMLRPCServer.set_server_title(server_title)

   Define o título usado na documentação HTML gerada. Este título será
   usado dentro do elemento "title" do HTML.

DocXMLRPCServer.set_server_name(server_name)

   Define o nome usado na documentação HTML gerada. Este nome
   aparecerá na parte superior da documentação gerada dentro de um
   elemento "h1".

DocXMLRPCServer.set_server_documentation(server_documentation)

   Define a descrição usada na documentação HTML gerada. Esta
   descrição aparecerá na documentação como um parágrafo, abaixo do
   nome do servidor.


DocCGIXMLRPCRequestHandler
==========================

A classe "DocCGIXMLRPCRequestHandler" é derivada de
"CGIXMLRPCRequestHandler" e fornece um meio de criar scripts CGI XML-
RPC autodocumentados. Solicitações HTTP POST são tratadas como
chamadas de método XML-RPC. As solicitações HTTP GET são tratadas
gerando documentação HTML no estilo pydoc. Isso permite que um
servidor forneça sua própria documentação baseada na web.

DocCGIXMLRPCRequestHandler.set_server_title(server_title)

   Define o título usado na documentação HTML gerada. Este título será
   usado dentro do elemento "title" do HTML.

DocCGIXMLRPCRequestHandler.set_server_name(server_name)

   Define o nome usado na documentação HTML gerada. Este nome
   aparecerá na parte superior da documentação gerada dentro de um
   elemento "h1".

DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)

   Define a descrição usada na documentação HTML gerada. Esta
   descrição aparecerá na documentação como um parágrafo, abaixo do
   nome do servidor.
