7.2 socket -- Interfaccia di rete di basso livello

Questo modulo fornisce un accesso all'interfaccia socket BSD. È disponibile su tutti i moderni sistemi Unix, Windows, MacOS, BeOS, OS/2 e probabilmente altre piattaforme.

Per un'introduzione alla programmazione dei socket (in C), leggere i seguenti libri: An Introductory 4.3BSD Interprocess Communication Tutorial, di Stuart Sechres e An Advanced 4.3BSD Interprocess Communication Tutorial, di Samuel J. Leffler et al, sia il Unix Programmer's Manual, Supplementary Documents 1 (sezione PS1:7 e PS1:8). I materiali di riferimento specifici per piattaforma per le varie chiamate di sistema relative ai socket sono un'ottima sorgente di informazioni sui dettagli della semantica dei socket. Per Unix, riferirsi alle pagine di manuale; per Windows, leggere le specifiche del WinSock (o WinSock 2). Per le API IPv6-ready, i lettori vorranno far riferimento all'RFC 2553 intitolato Basic Socket Interface Extensions for IPv6.

L'interfaccia Python è una traduzione diretta delle chiamate di sistema Unix e l'interfaccia di libreria per i socket in stile orientato agli oggetti di Python: la funzione socket() restituisce un oggetto socket i cui metodi implementano le varie chiamate di sistema dei socket. I tipi di parametro sono qualcosa di più alto livello rispetto all'interfaccia C: simile alle operazioni read() e write() sui file Python, l'allocazione del buffer sulle operazioni di ricezione è automatica, e la lunghezza del buffer è implicita nelle operazioni di invio.

Gli indirizzi socket sono indicati come a seguito: una singola stringa è usata per la famiglia di indirizzi AF_UNIX. Una coppia (host, porta) è usata per la famiglia di indirizzi AF_INET, dove host è una stringa rappresentante un hostname nella notazione dei domini Internet come 'daring.cwi.nl' o un indirizzo IPv4 come '100.50.200.5', mentre porta è un numero di porta intero. Per la famiglia di indirizzi AF_INET6, viene usata una tupla quadrupla (host, porta, flowinfo, scopeid), dove flowinfo e scopeid indicano i membri sin6_flowinfo e sin6_scope_id nella struttura struct sockaddr_in6 del C. Per i metodi del modulo socket, flowinfo e scopeid possono essere omessi solo per retrocompatibilità. Notare, comunque, che l'omissione di scopeid può causare problemi nella manipolazione di indirizzi IPv6. Altre famiglie di indirizzi non sono attualmente sopportate. Il formato dell'indirizzo richiesto da un particolare oggetto socket è automaticamente selezionato in base alla famiglia di indirizzi specificata quando l'oggetto socket è stato creato.

Per gli indirizzi IPv4, sono accettate due forme speciali al posto di un indirizzo di un host: la stringa vuota rappresenta INADDR_ANY, e la stringa '<broadcast>' rappresenta INADDR_BROADCAST. Il comportamento non è disponibile con IPv6 per retrocompatibilità, quindi, si potrebbe volerle evitare se si ha l'intenzione di supportare IPv6 nei propri programmi Python.

Se si usa un hostname in un segmento di rete composto da indirizzi socket IPv4/v6, il programma potrebbe mostrare un comportamento non deterministico, visto che Python usa il primo indirizzo restituito dalla risoluzione DNS. L'indirizzo socket sarebbe risolto differentemente in un attuale indirizzo IPv4/v6 reale, a seconda dei risultati della risoluzione DNS e/o la configurazione dell'host. Per un comportamento deterministico usare un indirizzo numerico nel segmento di rete.

Tutti gli errori sollevano eccezioni. Possono essere sollevate le consuete eccezioni per tipi di argomento non validi e condizioni di out-of-memory; errori relativi ai socket o alla semantica degli indirizzi sollevano l'errore socket.error.

La modalità non bloccante è supportata attraverso setblocking(). Una sua generalizzazione basata sui timeout è supportata attraverso settimeout().

Il modulo socket esporta le seguenti costanti e funzioni:

exception error
Questa eccezione viene sollevata per errori relativi ai socket. Il valore che la accompagna è una stringa che dice cosa è andato storto oppure una coppia (errno, string) che rappresenta un errore restituito da una chiamata di sistema, simile al valore che accompagna os.error. Vedere il modulo errno, che contiene nomi per i codici di errore definiti dal sistema operativo sottostante.

exception herror
Questa eccezione viene sollevata per errori relativi agli indirizzi, i.e. per funzioni che usano h_errno nell'API C, inclusi gethostbyname_ex() e gethostbyaddr().

Il valore che la accompagna è una coppia (h_errno, string) che rappresenta un errore restituito da una chiamata di libreria. string rappresenta la descrizione di h_errno, come restituito dalla funzione C hstrerror(). Il valore di error corrisponderà con una delle costanti EAI_* definite in questo modulo.

exception gaierror
Questa eccezione è sollevata per errori relativi agli indirizzi, per getaddrinfo() e getnameinfo(). Il valore che la accompagna è una coppia (error, string) che rappresenta un errore restituito da una chiamata di libreria. string rappresenta la descrizione di error, come restituito dalla funzione C gai_strerror().

exception timeout
Questa eccezione viene sollevata quando avviene un timeout su un socket che aveva abilitati i timeout attraverso una precedente chiamata a settimeout(). Il valore che la accompagna è una stringa il cui valore corrente è sempre ``timed out''. Nuovo nella versione 2.3.

AF_UNIX
AF_INET
AF_INET6
Queste costanti rappresentano le famiglie degli indirizzi (e protocolli), usate per il primo argomento di socket(). Se la constante constantAF_UNIX non è definita significa che questo protocollo non è supportato.

SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_RDM
SOCK_SEQPACKET
Queste costanti rappresentano i tipi di socket, usati per il secondo argomento di socket(). (solo SOCK_STREAM e SOCK_DGRAM appaiono utili in genere.)

SO_*
SOMAXCONN
MSG_*
SOL_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*
Molte costanti di queste forme, trattate nella documentazione Unix sui socket e/o sul protocollo IP, sono inoltre definite nel modulo socket. Generalmente sono usate negli argomenti dei metodi setsockopt() e getsockopt() degli oggetti socket. In molti casi, solo quei simboli definiti nelle intestazioni dei file Unix sono qui definiti; per alcuni di essi, sono forniti valori predefiniti.

has_ipv6
Questa costante contiene un valore booleano che indica se l'IPv6 è supportato su questa piattaforma. Nuovo nella versione 2.3.

getaddrinfo( host, porta[, family[, socktype[, proto[, flags]]]])
Risolve l'argomento host/porta, in una sequenza di tuple di 5 elementi contenenti tutti gli argomenti necessari per la manipolazione dei socket. host è il nome di un dominio, una stringa rappresentante un indirizzo IPv4/v6 oppure None. porta è una stringa contente il nome di un servizio (come 'http'), una rappresentazione numerica del numero della porta oppure None.

Il resto degli argomenti sono facoltativi e devono essere numerici se specificati. Per host e porta, devono essere passate una stringa vuota o None, è possibile passare NULL all'API C. La funzione getaddrinfo() restituisce una lista di tuple di 5 elementi con la seguente struttura:

(family, socktype, proto, canonname, sockaddr)

family, socktype e proto sono tutti interi che devono essere passati alla funzione socket(). canonname è una stringa rappresentante il nome canonico dell'host. Può essere un indirizzo numerico IPv4/v6 quando AI_CANONNAME viene specificato per un host numerico. sockaddr è una tupla che descrive un indirizzo socket, come descritto sopra. Leggere i sorgenti di httplib ed altri moduli di libreria per un utilizzo tipico della funzione. Nuovo nella versione 2.2.

getfqdn( [nome])
Restituisce un nome di dominio pienamente qualificato per nome. Se nome è omesso o vuoto, viene interpretato come l'host locale. Per trovare il nome pienamente qualificato, viene controllato l'hostname restituito da gethostbyaddr(), quindi fatto l'alias per l'host, se disponibile. Viene selezionato il primo nome contenente un punto. Nel caso non sia disponibile un nome di dominio pienamente qualificato, viene restituito l'hostname. Nuovo nella versione 2.0.

gethostbyname( hostname)
Traduce un host name nel formato di indirizzi IPv4. L'indirizzo IPv4 viene restituito in una stringa, come '100.50.200.5'. Se l'host name è esso stesso un indirizzo IPv4 viene restituito invariato. Vedere gethostbyname_ex() per un'interfaccia più completa. gethostbyname() non supporta la risoluzione dei nomi IPv6m e getaddrinfo() dovrebbe essere usata al suo posto per il supporto al dual stack IPv4/v6.

gethostbyname_ex( hostname)
Traduce un hostname in un formato di indirizzo IPv4, interfaccia estesa. Restituisce un tripla (hostname, aliaslist, ipaddrlist) dove hostname è il nome dell'host primario in risposta all'ip_address dato, aliaslist è una lista (che può essere vuota) di hostname alternativi per lo stesso indirizzo, e ipaddrlist è una lista di indirizzi IPv4 per la stessa interfaccia sullo stesso host (spesso ma non sempre un singolo indirizzo). gethostbyname_ex() non supporta la risoluzione dei nomi IPv6, e dovrebbe essere usata getaddrinfo() per il supporto al dual stack IPv4/v6.

gethostname( )
Restituisce una stringa contenente l'hostname della macchina in cui è in esecuzione l'interprete Python. Se si vuol sapere l'indirizzo IP corrente della macchina, si può usare gethostbyname(gethostname()). Questa operazione assume che ci sia una valida reciprocità tra l'indirizzo dell'host e l'host, e questo non sempre avviene. Notare: gethostname() non restituisce sempre il nome di dominio pienamente qualificato; usare gethostbyaddr(gethostname()) (vedere sotto).

gethostbyaddr( ip_address)
Restituisce una tripla (hostname, aliaslist, ipaddrlist) dove hostname è il nome dell'host primario che risponde all'indirizzo ip_address dato, aliaslist è una lista (che può essere vuota) di nomi di host alternativi per lo stesso indirizzo, e ipaddrlist è una lista di indirizzi IPv4/v6 per la stessa interfaccia sullo stesso host (che più facilmente contiene solo un singolo indirizzo). Per trovare il nome di dominio pienamente qualificato, usare la funzione getfqdn(). gethostbyaddr supporta sia IPv4 che IPv6.

getnameinfo( sockaddr, opzioni)
Traduce un indirizzo socket sockaddr in una coppia (host, porta). A seconda delle impostazioni delle opzioni, il risultato può contenere un nome di dominio pienamente qualificato o una rappresentazione numerica dell'indirizzo in host. In modo simile porta può contenere una stringa con il nome della porta o la rappresentazione numerica del numero della porta. Nuovo nella versione 2.2.

getprotobyname( protocolname)
Traduce il nome di un protocollo Internet (per esempio, 'icmp') in una costante adatta per essere passata come terzo argomento (facoltativo) della funzione socket(). Solitamente serve solo per socket aperti in modalità ``raw'' (SOCK_RAW); per le normali modalità adottate con i socket, il protocollo corretto è scelto automaticamente se è omesso oppure zero.

getservbyname( servicename, protocolname)
Traduce il nome di un servizio Internet e il nome di un protocollo nel numero di una porta per quel servizio. Il nome del protocollo dovrebbe essere 'tcp' o 'udp'.

socket( [family[, type[, proto]]])
Crea un nuovo socket usando i dati per la famiglia di indirizzo, family, il tipo di socket type ed il numero di protocollo proto. L'indirizzo della famiglia dovrebbe essere AF_INET (predefinito), AF_INET6 o AF_UNIX. Il tipo di socket dovrebbe essere SOCK_STREAM (predefinito), SOCK_DGRAM o forse una delle altre costanti "SOCK_". Il numero di protocollo è solitamente zero e può essere omesso in quel caso.

ssl( sock[, keyfile, certfile])
Inizializza una connessione SSL sul socket sock. keyfile è il nome di un file formattato PEM che contiene la propria chiave privata. certfile è un file chiave certificato e formattato PEM. In caso di successo, viene restituito un nuovo oggetto SSLObject.

Questa funzione non effettua nessuna verifica di certificazione!

fromfd( fd, family, type[, proto])
Costruisce un oggetto socket da un descrittore di file esistente (un intero restituito dal metodo fileno() dell'oggetto file). Famiglia di indirizzo, tipo di socket e numero di protocollo sono identici a quelli della funzione socket() vista sopra. Il descrittore di file dovrebbe riferirsi ad un socket, ma questo non viene controllato -- le operazioni susseguenti sull'oggetto potrebbero fallire se il descrittore di file non è valido. Questa funzione è raramente impiegata, ma può essere usata per ricevere o impostare opzioni sui socket su un socket passato ad un programma come standard input o output (come in un server all'avvio, dal demone inet Unix). Il socket si assume essere bloccante. Disponibilità: Unix.

ntohl( x)
Converte interi di 32-bit dal byte order di rete a quello di host. Su macchine dove il byte order dell'host è lo stesso di quello di rete, non avviene nulla; altrimenti, esegue un operazione di swap a 4 byte.

ntohs( x)
Converte interi di 16-bit dal byte order di rete a quello di host. Su macchine dove il byte order dell'host è lo stesso di quello di rete, non avviene nulla; altrimenti, esegue un operazione di swap a 2 bit.

htonl( x)
Converte interi di 32-bit dal byte order dell'host a quello di rete. Su macchine dove il byte order dell'host è lo stesso di quello di rete, non avviene nulla; altrimenti, esegue un operazione di swap a 4 bit.

htons( x)
Converte interi di 16-bit dal byte order dell'host a quello di rete. Su macchine dove il byte order dell'host è lo stesso di quello di rete, non avviene nulla; altrimenti, esegue un operazione di swap a 2 bit.

inet_aton( ip_string)
Converte un indirizzo IPv4 dalla stringa in formato punteggiato (per esempio, '123.45.67.89') in un formato binario di pacchetto a 32-bit, come una stringa lunga 4 caratteri. Ciò risulta utile quando bisogna conversare con un programma che utilizza la libreria standard C e necessita di oggetti di tipo struct in_addr, che è il tipo C per i pacchetti binari 32-bit che questa funzione restituisce.

Se la stringa dell'indirizzo passata a questa funzione non è valida, verrà sollevata un'eccezione socket.error. Notare che la validità dipende dall'implementazione sottostante in C di inet_aton().

inet_aton() non supporta IPv6, dovrebbe essere usata al suo posto getnameinfo() per il supporto al dual stack IPv4/v6.

inet_ntoa( packed_ip)
Converte l'indirizzo di un pacchetto a 32-bit (una stringa lunga 4 caratteri) nella rappresentazione standard in quartine-puntate (per esempio, '123.45.67.89'). Ciò risulta utile quando bisogna conversare con un programma che utilizza la libreria standard C e necessita di oggetti del tipo struct in_addr, che è il tipo C per i pacchetti binari 32-bit che questa funzione prende per argomento.

Se la stringa passata a questa funzione non è esattamente di 4 byte, verrà sollevata un'eccezione socket.error. inet_ntoa() non supporta l'IPv6, dovrebbe essere usata al suo posto getnameinfo() per il supporto al dual stack IPv4/v6.

inet_pton( address_family, ip_string)
Converte un indirizzo IP dal suo formato specifico di famiglia in un formato di pacchetto binario. inet_pton() è utile quando una libreria o un protocollo di rete richiedono un oggetto del tipo struct in_addr (simile ad inet_aton()) o struct in6_addr.

I valori supportati per address_family sono al momento AF_INET e AF_INET6. Se la stringa di indirizzo IP ip_string non è valida, verrà sollevata un'eccezione socket.error. Notare che la validità dipende sia dal valore di address_family che dall'implementazione sottostante di inet_pton().

Disponibilità: Unix (forse non tutte le piattaforme). Nuovo nella versione 2.3.

inet_ntop( address_family, packed_ip)
Converte un indirizzo IP di un pacchetto (una stringa di un qualche numero di caratteri) nella sua standard, specifica per la sua famiglia, stringa rappresentativa (per esempio, '7.10.0.5' or '5aef:2b::8')). inet_ntop() è utile quando una libreria o protocollo di rete restituisce un oggetto di tipo struct in_addr (simile a inet_ntoa()) o struct in6_addr.

I valori supportati per address_family sono attualmente AF_INET e AF_INET6. Se la stringa packed_ip non è della lunghezza corretta per la specifica famiglia di indirizzi, sarà sollevata un'eccezione ValueError. Per gli errori provenienti dalla chiamata a inet_ntop() sarà sollevata un'eccezione socket.error.

Disponibilità: Unix (forse non tutte le piattaforme). Nuovo nella versione 2.3.

getdefaulttimeout( )
Restituisce il timeout predefinito in secondi floating per i nuovi oggetti socket. Il valore None indica che i nuovi oggetti socket non hanno timeout. Quando il modulo socket è appena importato, il suo valore predefinito è None. Nuovo nella versione 2.3.

setdefaulttimeout( timeout)
Imposta il timeout predefinito in secondi (numero a virgola mobile) per i nuovi oggetti socket. Il valore None indica che i nuovi oggetti socket non hanno timeout. Quando il modulo socket è appena importato, il suo valore predefinito è None. Nuovo nella versione 2.3.

SocketType
Questo è un tipo di oggetto Python che rappresenta il tipo oggetto socket. È lo stesso tipo di type(socket(...)).

Vedete anche:

Modulo SocketServer:
Classi che semplificano la scrittura di server di rete.



Subsections
Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.