20.24. SimpleXMLRPCServer — Basic XML-RPC server

Nota

The SimpleXMLRPCServer module has been merged into xmlrpc.server in Python 3. The 2to3 tool will automatically adapt imports when converting your sources to Python 3.

Novo na versão 2.2.

Source code: Lib/SimpleXMLRPCServer.py

The SimpleXMLRPCServer 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.

class SimpleXMLRPCServer.SimpleXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]])

Create a new server instance. This class provides methods for registration of functions that can be called by the XML-RPC protocol. The requestHandler parameter should be a factory for request handler instances; it defaults to SimpleXMLRPCRequestHandler. The addr and requestHandler parameters are passed to the SocketServer.TCPServer constructor. If logRequests is true (the default), requests will be logged; setting this parameter to false will turn off logging. The allow_none and encoding parameters are passed on to xmlrpclib and control the XML-RPC responses that will be returned from the server. The bind_and_activate parameter controls whether server_bind() and server_activate() are called immediately by the constructor; it defaults to true. Setting it to false allows code to manipulate the allow_reuse_address class variable before the address is bound.

Alterado na versão 2.5: The allow_none and encoding parameters were added.

Alterado na versão 2.6: The bind_and_activate parameter was added.

class SimpleXMLRPCServer.CGIXMLRPCRequestHandler([allow_none[, encoding]])

Create a new instance to handle XML-RPC requests in a CGI environment. The allow_none and encoding parameters are passed on to xmlrpclib and control the XML-RPC responses that will be returned from the server.

Novo na versão 2.3.

Alterado na versão 2.5: The allow_none and encoding parameters were added.

class SimpleXMLRPCServer.SimpleXMLRPCRequestHandler

Create a new request handler instance. This request handler supports POST requests and modifies logging so that the logRequests parameter to the SimpleXMLRPCServer constructor parameter is honored.

20.24.1. Objetos de SimpleXMLRPCServer

The SimpleXMLRPCServer class is based on SocketServer.TCPServer and provides a means of creating simple, stand alone XML-RPC servers.

SimpleXMLRPCServer.register_function(function[, name])

Register a function that can respond to XML-RPC requests. If name is given, it will be the method name associated with function, otherwise function.__name__ will be used. name can be either a normal or Unicode string, and may contain characters not legal in Python identifiers, including the period character.

SimpleXMLRPCServer.register_instance(instance[, allow_dotted_names])

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

Alterado na versão 2.3.5,: 2.4.1 allow_dotted_names was added to plug a security hole; prior versions are insecure.

SimpleXMLRPCServer.register_introspection_functions()

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

Novo na versão 2.3.

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

Novo na versão 2.5.

SimpleXMLRPCRequestHandler.encode_threshold

If this attribute is not None, responses larger than this value will be encoded using the gzip transfer encoding, if permitted by the client. The default is 1400 which corresponds roughly to a single TCP packet.

Novo na versão 2.7.

20.24.1.1. Exemplo de SimpleXMLRPCServer

Código do servidor:

from SimpleXMLRPCServer import SimpleXMLRPCServer
from SimpleXMLRPCServer import SimpleXMLRPCRequestHandler

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

# Create server
server = SimpleXMLRPCServer(("localhost", 8000),
                            requestHandler=RequestHandler)
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 'div').
class MyFuncs:
    def div(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 xmlrpclib

s = xmlrpclib.ServerProxy('http://localhost:8000')
print s.pow(2,3)  # Returns 2**3 = 8
print s.add(2,3)  # Returns 5
print s.div(5,2)  # Returns 5//2 = 2

# Print list of available methods
print s.system.listMethods()

The following SimpleXMLRPCServer example is included in the module Lib/SimpleXMLRPCServer.py:

server = SimpleXMLRPCServer(("localhost", 8000))
server.register_function(pow)
server.register_function(lambda x,y: x+y, 'add')
server.register_multicall_functions()
server.serve_forever()

This demo server can be run from the command line as:

python -m SimpleXMLRPCServer

Example client code which talks to the above server is included with Lib/xmlrpclib.py:

server = ServerProxy("http://localhost:8000")
print server
multi = MultiCall(server)
multi.pow(2, 9)
multi.add(5, 1)
multi.add(24, 11)
try:
    for response in multi():
        print response
except Error, v:
    print "ERROR", v

And the client can be invoked directly using the following command:

python -m xmlrpclib

20.24.2. CGIXMLRPCRequestHandler

The CGIXMLRPCRequestHandler class can be used to handle XML-RPC requests sent to Python CGI scripts.

CGIXMLRPCRequestHandler.register_function(function[, name])

Register a function that can respond to XML-RPC requests. If name is given, it will be the method name associated with function, otherwise function.__name__ will be used. name can be either a normal or Unicode string, and may contain characters not legal in Python identifiers, including the period character.

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