xmlrpc.server — Grundläggande XML-RPC-servrar

Källkod: Lib/xmlrpc/server.py

Modulen xmlrpc.server tillhandahåller ett grundläggande serverramverk för XML-RPC-servrar skrivna i Python. Servrar kan antingen vara fristående, med SimpleXMLRPCServer, eller inbäddade i en CGI-miljö, med CGIXMLRPCRequestHandler.

Varning

Modulen xmlrpc.server är inte säker mot skadligt konstruerade data. Om du behöver analysera icke betrodda eller oautentiserade data, se XML-säkerhet.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

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

Skapa en ny serverinstans. Denna klass tillhandahåller metoder för registrering av funktioner som kan anropas av XML-RPC-protokollet. Parametern requestHandler bör vara en fabrik för requesthandler-instanser; standardvärdet är SimpleXMLRPCRequestHandler. Parametrarna addr och requestHandler skickas till konstruktören för socketserver.TCPServer. Om logRequests är true (standard) kommer förfrågningar att loggas; om parametern är false stängs loggning av. Parametrarna allow_none och encoding skickas vidare till xmlrpc.client och styr de XML-RPC-svar som kommer att returneras från servern. Parametern bind_and_activate styr om server_bind() och server_activate() anropas omedelbart av konstruktören; standardvärdet är true. Om den sätts till false kan koden manipulera klassvariabeln allow_reuse_address innan adressen är bunden. Parametern use_builtin_types skickas till funktionen loads() och styr vilka typer som bearbetas när datum-/tidsvärden eller binära data tas emot; standardvärdet är false.

Ändrad i version 3.3: Flaggan use_builtin_types har lagts till.

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

Skapa en ny instans för att hantera XML-RPC-förfrågningar i en CGI-miljö. Parametrarna allow_none och encoding skickas vidare till xmlrpc.client och styr de XML-RPC-svar som returneras från servern. Parametern use_builtin_types skickas till funktionen loads() och styr vilka typer som behandlas när datum-/tidsvärden eller binära data tas emot; standardvärdet är false.

Ändrad i version 3.3: Flaggan use_builtin_types har lagts till.

class xmlrpc.server.SimpleXMLRPCRequestHandler

Skapa en ny instans av request handler. Denna request handler stöder POST requests och modifierar loggningen så att parametern logRequests till SimpleXMLRPCServer constructor parameter respekteras.

SimpleXMLRPCServer-objekt

Klassen SimpleXMLRPCServer är baserad på socketserver.TCPServer och gör det möjligt att skapa enkla, fristående XML-RPC-servrar.

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

Registrerar en funktion som kan svara på XML-RPC-förfrågningar. Om name anges kommer det att vara det metodnamn som associeras med function, annars kommer function.__name__ att användas. name är en sträng och kan innehålla tecken som inte är tillåtna i Python-identifierare, inklusive periodtecknet.

Denna metod kan också användas som en dekorator. När den används som en dekorator kan name endast anges som ett nyckelordsargument för att registrera function under name. Om inget namn anges kommer function.__name__ att användas.

Ändrad i version 3.7: register_function() kan användas som dekorator.

SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)

Registrera ett objekt som används för att exponera metodnamn som inte har registrerats med hjälp av register_function(). Om instance innehåller en _dispatch()-metod, anropas den med det begärda metodnamnet och parametrarna från begäran. Dess API är def _dispatch(self, method, params) (observera att params inte representerar en variabel argumentlista). Om den anropar en underliggande funktion för att utföra sin uppgift, kallas den funktionen som func(*params) och utökar parameterlistan. Returvärdet från _dispatch() returneras till klienten som resultat. Om instance inte har någon _dispatch()-metod, söks den efter ett attribut som matchar namnet på den begärda metoden.

Om det valfria argumentet allow_dotted_names är true och instansen inte har någon _dispatch()-metod, och det begärda metodnamnet innehåller punkter, söks varje komponent i metodnamnet individuellt, vilket innebär att en enkel hierarkisk sökning utförs. Det värde som hittas vid denna sökning anropas sedan med parametrarna från begäran och returvärdet skickas tillbaka till klienten.

Varning

Om du aktiverar alternativet allow_dotted_names får inkräktare tillgång till modulens globala variabler och kan köra godtycklig kod på din dator. Använd endast det här alternativet i ett säkert, slutet nätverk.

SimpleXMLRPCServer.register_introspection_functions()

Registrerar XML-RPC introspektionsfunktionerna system.listMethods, system.methodHelp och system.methodSignature.

SimpleXMLRPCServer.register_multicall_functions()

Registrerar XML-RPC multicall-funktionen system.multicall.

SimpleXMLRPCRequestHandler.rpc_paths

Ett attributvärde som måste vara en tupel som listar giltiga sökvägsdelar av URL:en för mottagning av XML-RPC-förfrågningar. Förfrågningar som skickas till andra sökvägar kommer att resultera i ett HTTP-fel 404 ”no such page”. Om denna tupel är tom kommer alla sökvägar att betraktas som giltiga. Standardvärdet är ('/', '/RPC2').

Exempel på SimpleXMLRPCServer

Serverkod:

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

Följande klientkod anropar de metoder som görs tillgängliga av den föregående servern:

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() kan också användas som en dekorator. Det föregående serverexemplet kan registrera funktioner på ett dekorativt sätt:

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

Följande exempel som ingår i modulen Lib/xmlrpc/server.py visar en server som tillåter prickade namn och registrerar en multicall-funktion.

Varning

Om du aktiverar alternativet allow_dotted_names får inkräktare tillgång till modulens globala variabler och kan köra godtycklig kod på din dator. Använd detta exempel endast inom ett säkert, slutet nätverk.

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)

Denna ExampleService-demo kan startas från kommandoraden:

python -m xmlrpc.server

Klienten som interagerar med ovanstående server ingår i Lib/xmlrpc/client.py:

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

försök:
    print(server.currentTime.getCurrentTime())
except Error as v:
    print("ERROR", v)

multi = MultiCall(server)
multi.getData()
multi.pow(2,9)
multi.add(1,2)
försök:
    for svar i multi():
        print(svar)
except Error as v:
    print("ERROR", v)

Denna klient som interagerar med demo XMLRPC-servern kan anropas som:

python -m xmlrpc.client

CGIXMLRPCFörfrågningshanterare

Klassen CGIXMLRPCRequestHandler kan användas för att hantera XML-RPC-förfrågningar som skickas till Python CGI-skript.

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

Registrerar en funktion som kan svara på XML-RPC-förfrågningar. Om name anges kommer det att vara det metodnamn som associeras med function, annars kommer function.__name__ att användas. name är en sträng och kan innehålla tecken som inte är tillåtna i Python-identifierare, inklusive periodtecknet.

Denna metod kan också användas som en dekorator. När den används som en dekorator kan name endast anges som ett nyckelordsargument för att registrera function under name. Om inget namn anges kommer function.__name__ att användas.

Ändrad i version 3.7: register_function() kan användas som dekorator.

CGIXMLRPCRequestHandler.register_instance(instance)

Registrera ett objekt som används för att exponera metodnamn som inte har registrerats med hjälp av register_function(). Om instance innehåller en _dispatch()-metod anropas den med det begärda metodnamnet och parametrarna från begäran; returvärdet returneras till klienten som resultat. Om instance inte har någon _dispatch()-metod söks den efter ett attribut som matchar namnet på den begärda metoden; om det begärda metodnamnet innehåller perioder söks varje komponent i metodnamnet individuellt, vilket innebär att en enkel hierarkisk sökning utförs. Det värde som hittas vid denna sökning anropas sedan med parametrarna från begäran, och returvärdet skickas tillbaka till klienten.

CGIXMLRPCRequestHandler.register_introspection_functions()

Registrera XML-RPC introspektionsfunktionerna system.listMethods, system.methodHelp och system.methodSignature.

CGIXMLRPCRequestHandler.register_multicall_functions()

Registrera XML-RPC multicall-funktionen system.multicall.

CGIXMLRPCRequestHandler.handle_request(request_text=None)

Hantera en XML-RPC-begäran. Om request_text anges bör det vara POST-data som tillhandahålls av HTTP-servern, annars kommer innehållet i stdin att användas.

Exempel:

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

Dokumentation av XMLRPC-server

Dessa klasser utökar ovanstående klasser för att servera HTML-dokumentation som svar på HTTP GET-begäranden. Servrar kan antingen vara fristående, med DocXMLRPCServer, eller inbäddade i en CGI-miljö, med DocCGIXMLRPCRequestHandler.

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

Skapa en ny serverinstans. Alla parametrar har samma betydelse som för SimpleXMLRPCServer; requestHandler är standard för DocXMLRPCRequestHandler.

Ändrad i version 3.3: Flaggan use_builtin_types har lagts till.

class xmlrpc.server.DocCGIXMLRPCRequestHandler

Skapa en ny instans för att hantera XML-RPC-begäranden i en CGI-miljö.

class xmlrpc.server.DocXMLRPCRequestHandler

Skapa en ny instans av request handler. Denna request handler stöder XML-RPC POST requests, documentation GET requests och modifierar loggning så att parametern logRequests till DocXMLRPCServer constructor parameter respekteras.

DocXMLRPCServer-objekt

Klassen DocXMLRPCServer är härledd från SimpleXMLRPCServer och gör det möjligt att skapa självdokumenterande, fristående XML-RPC-servrar. HTTP POST-förfrågningar hanteras som XML-RPC-metodanrop. HTTP GET-förfrågningar hanteras genom att generera HTML-dokumentation i pydoc-stil. Detta gör att en server kan tillhandahålla sin egen webbaserade dokumentation.

DocXMLRPCServer.set_server_title(server_title)

Ange den titel som används i den genererade HTML-dokumentationen. Denna titel kommer att användas inuti HTML-elementet ”title”.

DocXMLRPCServer.set_server_name(server_name)

Ange det namn som används i den genererade HTML-dokumentationen. Detta namn kommer att visas högst upp i den genererade dokumentationen i ett ”h1”-element.

DocXMLRPCServer.set_server_documentation(server_documentation)

Ange den beskrivning som används i den genererade HTML-dokumentationen. Beskrivningen kommer att visas som ett stycke under servernamnet i dokumentationen.

DocCGIXMLRPCRequestHandler

Klassen DocCGIXMLRPCRequestHandler är härledd från CGIXMLRPCRequestHandler och gör det möjligt att skapa självdokumenterande XML-RPC CGI-skript. HTTP POST-förfrågningar hanteras som XML-RPC-metodanrop. HTTP GET-begäranden hanteras genom att generera HTML-dokumentation i pydoc-stil. Detta gör att en server kan tillhandahålla sin egen webbaserade dokumentation.

DocCGIXMLRPCRequestHandler.set_server_title(server_title)

Ange den titel som används i den genererade HTML-dokumentationen. Denna titel kommer att användas inuti HTML-elementet ”title”.

DocCGIXMLRPCRequestHandler.set_server_name(server_name)

Ange det namn som används i den genererade HTML-dokumentationen. Detta namn kommer att visas högst upp i den genererade dokumentationen i ett ”h1”-element.

DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)

Ange den beskrivning som används i den genererade HTML-dokumentationen. Beskrivningen kommer att visas som ett stycke under servernamnet i dokumentationen.