# `xmlrpc.server` — Servidores XML-RPC básicos

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

O módulo `xmlrpc.server` fornece um framework básico de servidor para servidores XML-RPC escritos em Python. Os servidores podem ser independentes, usando `SimpleXMLRPCServer`, ou incorporados em um ambiente CGI, usando `CGIXMLRPCRequestHandler`.

Aviso

O módulo `xmlrpc.server` não é seguro contra dados criados com códigos maliciosos. Se você precisar analisar dados não confiáveis ou não autenticados, consulte Vulnerabilidades em XML.

Disponibilidade: não Emscripten, não WASI.

Este módulo não funciona ou não está disponível em plataformas WebAssembly `wasm32-emscripten` e `wasm32-wasi`. 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.

## Objetos de SimpleXMLRPCServer

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

### Exemplo de SimpleXMLRPCServer

Código do servidor:

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

    # Restrict to a particular path.
    class RequestHandler(SimpleXMLRPCRequestHandler):
        rpc_paths = ('/RPC2',)

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

        # Register pow() function; this will use the value of
        # pow.__name__ as the name, which is just 'pow'.
        server.register_function(pow)

        # Register a function under a different name
        def adder_function(x, y):
            return x + y
        server.register_function(adder_function, 'add')

        # Register an instance; all the methods of the instance are
        # published as XML-RPC methods (in this case, just 'mul').
        class MyFuncs:
            def mul(self, x, y):
                return x * y

        server.register_instance(MyFuncs())

        # Run the server's main loop
        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

    # Print list of available methods
    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()

        # Register pow() function; this will use the value of
        # pow.__name__ as the name, which is just 'pow'.
        server.register_function(pow)

        # Register a function under a different name, using
        # register_function as a decorator. *name* can only be given
        # as a keyword argument.
        @server.register_function(name='add')
        def adder_function(x, y):
            return x + y

        # Register a function under 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

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 este exemplo apenas em uma rede fechada e segura.

    import datetime

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

        class currentTime:
            @staticmethod
            def getCurrentTime():
                return datetime.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.

## Objetos de DocXMLRPCServer

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.