17.2. socket - Interface de rede de baixo nível

17.2.

socket

- Interface de rede de baixo nível

Nota : Algum comportamento pode ser dependente da plataforma, uma vez que as

chamadas são feitas para as APIs do soquete do sistema operacional.

Para uma introdução à programação de socket (em C), veja os seguintes artigos: Um Tutorial de Comunicação Interprocessal do 4.3BSD Introdutório, por Stuart Sechrest e um Tutorial Avançado de Comunicação entre Processos do 4.3BSD, por Samuel J. Leffler et al, ambos no Manual do Programador UNIX , Documentos Complementares 1 (seções PS1: 7 e PS1: 8). O material de referência específico da plataforma para as várias chamadas do sistema relacionadas ao soquete também é uma valiosa fonte de informações sobre os detalhes da semântica do soquete. Para Unix, consulte as páginas de manual; para Windows, consulte a especificação WinSock (ou Winsock 2). Para APIs prontas para IPv6, os leitores podem querer consultar RFC 3493 intitulado Basic Socket Interface Extensions para IPv6.

A interface Python é uma transliteração direta da interface de biblioteca e chamada de sistema Unix para soquetes para o estilo orientado a objeto do Python: a função socket() retorna um objeto de soquete cujos métodos implementam as várias chamadas do sistema de soquete. Os tipos de parâmetros são um pouco mais altos do que na interface C: como nas operações read() e write() em arquivos Python, a alocação de buffer nas operações de

recepção é automática e o tamanho do buffer é implícito nas operações de envio.

Os endereços de soquete são representados da seguinte maneira: Uma única string é usada para a família de endereços AF_UNIX . Um par (host, port) é usado para a família de endereços AF_INET , onde host é uma string que representa um nome de host na notação de domínio da Internet como 'daring.cwi.nl' ou um endereço IPv4 como '100.50.200.5' e a porta é um inteiro. Para a família de endereços AF_INET6 , uma quatro tuplas (host, port, flowinfo, scopeid) é usada, onde flowinfo e scopeid representam sin6_flowinfo e sin6_scope_id membro em struct sockaddr_in6 em C. Para métodos de módulo de socket , flowinfo e scopeid podem ser omitidos apenas para retroceder compatibilidade. Observe, no entanto, que a omissão de scopeid pode causar problemas na manipulação de endereços IPv6 com escopo definido. Outras famílias de endereços não são suportadas atualmente. O formato de endereço requerido por um objeto de soquete específico é selecionado automaticamente com base na família de endereços especificada quando o objeto de soquete foi criado. Para endereços IPv4, dois formulários especiais são aceitos em vez de um endereço de host: a string vazia representa INADDR_ANY e a string '<broadcast>' representa INADDR_BROADCAST . O

comportamento não está disponível para o IPv6 para compatibilidade com versões anteriores, portanto, você pode evitá-los, caso pretenda oferecer suporte ao IPv6 com seus

programas em Python.

Se você usar um nome de host na parte do host do endereço de soquete IPv4 / v6, o programa poderá mostrar um comportamento não determinístico, pois o Python usa o primeiro endereço retornado da resolução de DNS. O endereço do soquete será resolvido de forma diferente em um endereço IPv4 / v6 real, dependendo dos resultados da resolução de DNS e / ou da configuração do host. Para comportamento determinístico, use um endereço numérico na parte do host .

Novo na versão 2.5: Os sockets AF_NETLINK são representados como pares pid, groups . Novo na versão 2.6: Suporte somente para Linux para TIPC também está disponível usando a família de endereços AF_TIPC . O TIPC é um protocolo de rede aberto, não baseado em IP,

projetado para uso em ambientes de computadores em cluster. Os endereços são representados por uma tupla e os campos dependem do tipo de endereço. O formulário geral da tupla é (addr_type, v1, v2, v3 [, scope]) , em que:

addr_type é um dos TIPC_ADDR_NAMESEQ , TIPC_ADDR_NAME ou TIPC_ADDR_ID .

O escopo é um dos TIPC_ZONE_SCOPE , TIPC_CLUSTER_SCOPE e TIPC_NODE_SCOPE .

Se addr_type for TIPC_ADDR_NAME , v1 é o tipo de servidor, v2 é o identificador de porta e v3

deve ser 0.

Se addr_type for TIPC_ADDR_NAMESEQ , então v1 é o tipo de servidor, v2 é o número de porta

inferior e v3 é o número de porta superior.

Se addr_type for TIPC_ADDR_ID , v1 é o nó, v2 é a referência e v3 deve ser definido como

0.

Todos os erros levantam exceções. As exceções normais para tipos de argumentos inválidos e condições de falta de memória podem ser levantadas; erros relacionados a semântica de socket ou endereço aumentam o erro socket.error .

O modo sem bloqueio é suportado através do setblocking() . Uma generalização disso baseada em tempos limite é suportada através de settimeout() .

O socket módulo exporta as seguintes constantes e funções: socket.exceçãosocket. error

Esta exceção é levantada para erros relacionados ao soquete. O valor que acompanha é uma cadeia que informa o que ocorreu de errado ou um par (errno, string) representando um erro retornado por uma chamada do sistema, semelhante ao valor que acompanha os.error . Veja o módulo errno , que contém nomes para os códigos de erro definidos pelo sistema operacional subjacente.

socket.exceçãosocket. herror

Esta exceção é levantada para erros relacionados ao endereço, ou seja, para funções que usam h_errno na API C, incluindo gethostbyname_ex() e gethostbyaddr() .

O valor que acompanha é um par (h_errno, string) representando um erro retornado por uma chamada de biblioteca. string representa a descrição de h_errno , conforme retornado pela função hstrerror() .

socket.exceçãosocket. gaierror

Esta exceção é levantada para erros relacionados ao endereço, para getaddrinfo() e getnameinfo() . O valor que acompanha é um par (error, string) representando um erro retornado por uma chamada de biblioteca. string representa a descrição do erro , conforme retornado pela função gai_strerror() . O valor do erro corresponderá a uma das

constantes EAI_* definidas neste módulo.

socket.exceçãosocket. timeout

Essa exceção é levantada quando ocorre um tempo limite em um soquete que teve tempo limite habilitado por meio de uma chamada anterior para settimeout() . O valor que

acompanha é uma string cujo valor atualmente é sempre "expirado". Novo na versão 2.3.

socket. AF_UNIX socket. AF_INET socket. AF_INET6

Essas constantes representam as famílias de endereço (e protocolo), usadas para o primeiro argumento para socket() . Se a constante AF_UNIX não estiver definida, este protocolo não é suportado.

socket. SOCK_STREAM socket. SOCK_DGRAM socket. SOCK_RAW socket. SOCK_RDM

socket. SOCK_SEQPACKET

Essas constantes representam os tipos de soquete, usados para o segundo argumento para socket() . (Somente SOCK_STREAM e SOCK_DGRAM parecem ser geralmente úteis.)

SO_* socket. SOMAXCONN MSG_* SOL_* IPPROTO_* IPPORT_* INADDR_* IP_* IPV6_*

EAI_* AI_* NI_* TCP_*

Muitas constantes desses formulários, documentadas na documentação do Unix sobre soquetes e / ou o protocolo IP, também são definidas no módulo do soquete. Eles geralmente são usados em argumentos para os métodos setsockopt() e getsockopt() de

objetos de soquete. Na maioria dos casos, apenas os símbolos definidos nos arquivos de cabeçalho Unix são definidos; para alguns símbolos, os valores padrão são fornecidos.

SIO_* RCVALL_*

Constantes para WSAIoctl do Windows (). As constantes são usadas como argumentos para o método ioctl() dos objetos de soquete.

Novo na versão 2.6. TIPC_*

Constantes relacionadas ao TIPC, correspondendo às exportadas pela API do soquete C. Veja a documentação da TIPC para mais informações.

Novo na versão 2.6. socket. has_ipv6

Essa constante contém um valor booleano que indica se o IPv6 é suportado nessa plataforma.

Novo na versão 2.3.

socket. create_connection( endereço

[

[

] ]

Conecte-se a um serviço TCP escutando no endereço da Internet (uma tupla 2 (host, port) ) e retorne o objeto de soquete. Esta é uma função de nível superior a socket.connect() : se host é um nome de host não numérico, ele tentará resolvê-lo para AF_INET e AF_INET6 e, em seguida, tentará se conectar a todos os endereços possíveis até que uma conexão seja bem-sucedida . Isso facilita a gravação de clientes compatíveis com IPv4 e IPv6.

A passagem do parâmetro de tempo limite opcional definirá o tempo limite na instância do soquete antes de tentar se conectar. Se nenhum timeout for fornecido, a configuração de tempo limite padrão global retornada por getdefaulttimeout() será usada.

Se fornecido, source_address deve ser uma 2-tupla (host, port) para o soquete a ser ligado como seu endereço de origem antes da conexão. Se host ou port forem '' ou 0, respectivamente, o comportamento padrão do SO será usado.

Novo na versão 2.6.

Alterado na versão 2.7: source_address foi adicionado.

socket. getaddrinfo( host , port

[

[

[

[

] ] ] ]

Traduza o argumento host / port em uma sequência de 5 tuplas que contém todos os argumentos necessários para criar um soquete conectado a esse serviço. host é um nome de domínio, uma representação de string de um endereço IPv4 / v6 ou None . port é um nome de serviço de cadeia de caracteres, como 'http' , um número de porta numérico ou None . Ao passar None como o valor de host e port , você pode passar NULL para a API C subjacente.

Os argumentos family , socktype e proto podem ser opcionalmente especificados para restringir a lista de endereços retornados. Por padrão, seu valor é 0 , o que significa que o intervalo total de resultados é selecionado. O argumento flags pode ser uma ou várias das constantes AI_* e influenciará como os resultados são calculados e retornados. Seu valor padrão é 0 . Por exemplo, o AI_NUMERICHOST desabilitará a resolução do nome de

domínio e gerará um erro se o host for um nome de domínio. A função retorna uma lista de 5 tuplas com a seguinte estrutura: (family, socktype, proto, canonname, sockaddr)

Nessas tuplas, family , socktype , proto são todos inteiros e devem ser passados para a função socket() . canonname será uma string representando o nome canônico do host se AI_CANONNAME parte do argumento flags ; mais canonname estará vazio. sockaddr é uma

tupla que descreve um endereço de socket, cujo formato depende da família retornada (a (address, port) 2-tuplas para AF_INET , um (address, port, flow info, scope id) 4-tupla para AF_INET6 ), e é destinado a ser passado para o método socket.connect() .

O exemplo a seguir busca informações de endereço para uma conexão TCP hipotética para example.org na porta 80 (os resultados podem ser diferentes em seu sistema se o IPv6 não estiver ativado):

>>> socket . getaddrinfo ( "example.org" , 80 , 0 , 0 , socket . IPPROTO_TCP ) [(10, 1, 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),

(2, 1, 6, '', ('93.184.216.34', 80))]

Novo na versão 2.2. socket. getfqdn(

[

]

Retornar um nome de domínio totalmente qualificado para o nome . Se o nome for omitido ou vazio, ele será interpretado como o host local. Para localizar o nome completo, o nome do host retornado por gethostbyaddr() é verificado, seguido por aliases para o host, se disponível. O primeiro nome que inclui um período é selecionado. Caso nenhum nome de domínio totalmente qualificado esteja disponível, o nome do host

retornado por gethostname() será retornado. Novo na versão 2.0.

socket. gethostbyname( hostname )

Traduza um nome de host para o formato de endereço IPv4. O endereço IPv4 é retornado como uma string, como '100.50.200.5' . Se o nome do host for um endereço IPv4, ele será retornado inalterado. Veja gethostbyname_ex() para uma interface mais completa. gethostbyname() não suporta resolução de nomes IPv6, e getaddrinfo() deve ser usado para suporte a pilha dupla IPv4 / v6.

socket. gethostbyname_ex ( hostname )

Traduzir um nome de host para o formato de endereço IPv4, interface estendida. Retorna um triplo (hostname, aliaslist, ipaddrlist) que hostname é o nome do host primário respondendo ao endereço ip dado, aliaslist é uma lista (possivelmente vazia) de nomes de host alternativos para o mesmo endereço e ipaddrlist é uma lista de endereços IPv4 para o mesma interface no mesmo host (geralmente, mas nem sempre, um único endereço). gethostbyname_ex() não suporta resolução de nomes IPv6, e getaddrinfo() deve ser usado para suporte a pilha dupla IPv4 / v6.

socket. gethostname( )

Retorna uma string contendo o nome do host da máquina onde o interpretador Python está executando no momento.

Se você quiser saber o endereço IP da máquina atual, você pode querer usar gethostbyname(gethostname()) . Essa operação pressupõe que há um mapeamento de endereço para host válido para o host e a suposição nem sempre é válida.

Nota: gethostname() nem sempre retorna o nome de domínio totalmente qualificado; use getfqdn() (veja acima).

socket. gethostbyaddr( ip_address )

Retornar um triplo (hostname, aliaslist, ipaddrlist) que hostname é o nome do host primário respondendo ao endereço ip_address , aliaslist é uma lista (possivelmente vazia) de nomes de host alternativos para o mesmo endereço e ipaddrlist é uma lista de endereços IPv4 / v6 para a mesma interface no mesmo host (provavelmente contendo apenas um único endereço). Para encontrar o nome de domínio totalmente qualificado, use a função getfqdn() . gethostbyaddr() suporta IPv4 e IPv6.

socket. getnameinfo( sockaddr , flags )

Traduza um endereço de soquete sockaddr em uma 2-tupla (host, port) . Dependendo das configurações de sinalizadores , o resultado pode conter um nome de domínio totalmente qualificado ou uma representação de endereço numérico no host . Da mesma forma, a porta pode conter um nome de porta de cadeia ou um número de porta numérico.

Novo na versão 2.2.

socket. getprotobyname ( protocolname )

Traduza um nome de protocolo da Internet (por exemplo, 'icmp' ) para uma constante adequada para passar como o terceiro argumento (opcional) para a função socket() . Isso geralmente é necessário apenas para soquetes abertos no modo "raw" ( SOCK_RAW ); para os modos normais de soquete, o protocolo correto é escolhido automaticamente se o protocolo for omitido ou zero.

socket. getservbyname( servicename

[

]

Traduza um nome de serviço e protocolo de Internet para um número de porta para esse serviço. O nome do protocolo opcional, se fornecido, deve ser 'tcp' ou 'udp' , caso contrário, qualquer protocolo corresponderá.

socket. getservbyport( port

[

]

Traduza um número de porta da Internet e nome de protocolo para um nome de serviço para esse serviço. O nome do protocolo opcional, se fornecido, deve ser 'tcp' ou 'udp' , caso contrário, qualquer protocolo corresponderá.

socket. socket (

[

[

[

] ] ]

Crie um novo soquete usando a família de endereços, tipo de soquete e número de protocolo fornecidos. A família de endereços deve ser AF_INET (o padrão), AF_INET6 ou AF_UNIX . O tipo de soquete deve ser SOCK_STREAM (o padrão), SOCK_DGRAM ou talvez uma das outras constantes SOCK_ . O número do protocolo é geralmente zero e pode ser omitido nesse caso.

socket. socketpair (

[

[

[

] ] ]

Construa um par de objetos de soquete conectados usando a família de endereços, tipo de soquete e número de protocolo fornecidos. Família de endereços, tipo de soquete e número de protocolo são como para a função socket() acima. A família padrão é AF_UNIX se definida na plataforma; caso contrário, o padrão é AF_INET . Disponibilidade: Unix. Novo na versão 2.4.

socket. fromfd ( fd , família , tipo

[

]

Duplique o descritor de arquivo fd (um inteiro retornado pelo método fileno() um objeto

de arquivo) e construa um objeto de soquete a partir do resultado. Família de endereços, tipo de soquete e número de protocolo são como para a função socket() acima. O descritor de arquivo deve se referir a um soquete, mas isso não é verificado - operações subseqüentes no objeto podem falhar se o descritor de arquivo for inválido. Essa função raramente é necessária, mas pode ser usada para obter ou configurar opções de soquete em um soquete passado para um programa como entrada ou saída padrão (como um servidor iniciado pelo daemon inet do Unix). Supõe-se que o soquete esteja no modo de bloqueio. Disponibilidade: Unix.

socket. ntohl( x )

Converte inteiros positivos de 32 bits da rede para a ordem de bytes do host. Nas máquinas em que a ordem de bytes do host é igual à ordem de bytes da rede, isso é um não operacional; caso contrário, ele executará uma operação de troca de 4 bytes.

socket. ntohs( x )

Converte inteiros positivos de 16 bits da rede para a ordem de bytes do host. Nas máquinas em que a ordem de bytes do host é igual à ordem de bytes da rede, isso é um não operacional; caso contrário, ele executará uma operação de troca de 2 bytes.

socket. htonl( x )

Converte números inteiros positivos de 32 bits da ordem de bytes do host para a rede. Nas máquinas em que a ordem de bytes do host é igual à ordem de bytes da rede, isso é um não operacional; caso contrário, ele executará uma operação de troca de 4 bytes. socket. htons( x )

Converte inteiros positivos de 16 bits da ordem de bytes do host para a rede. Nas máquinas em que a ordem de bytes do host é igual à ordem de bytes da rede, isso é um não operacional; caso contrário, ele executará uma operação de troca de 2 bytes.

socket. inet_aton( ip_string )

Converta um endereço IPv4 do formato de cadeia com quatro pontos (por exemplo, '123.45.67.89') para o formato binário compactado de 32 bits, como uma cadeia de quatro caracteres de comprimento. Isso é útil quando conversando com um programa que usa a biblioteca C padrão e precisa de objetos do tipo struct in_addr , que é o tipo C

para o binário compactado de 32 bits que esta função retorna.

inet_aton() também aceita strings com menos de três pontos; veja a página de manual Unix inet (3) para detalhes.

Se a cadeia de endereço IPv4 passada para essa função for inválida, o socket.error será gerado. Observe que exatamente o que é válido depende da implementação C subjacente de inet_aton() .

inet_aton() não suporta o IPv6, e o inet_pton() deve ser usado em vez do suporte à pilha dupla do IPv4 / v6.

socket. inet_ntoa( packed_ip )

Converta um endereço IPv4 compactado de 32 bits (uma cadeia de caracteres de quatro caracteres de comprimento) em sua representação padrão de cadeia com quatro pontos (por exemplo, '123.45.67.89'). Isso é útil quando conversando com um programa que usa a biblioteca C padrão e precisa de objetos do tipo struct in_addr , que é o tipo C

para os dados binários de 32 bits que esta função toma como argumento.

Se a string passada para esta função não tiver exatamente 4 bytes de comprimento, o socket.error será gerado. inet_ntoa() não suporta IPv6, e inet_ntop() deve ser usado no

lugar para suporte a IPv4 / v6 dual stack. socket. inet_pton( address_family , ip_string )

Converta um endereço IP de seu formato de string específico da família em um formato binário compactado.inet_pton() é útil quando uma biblioteca ou protocolo de rede chama um objeto do tipo struct in_addr (semelhante a inet_aton() ) ou struct in6_addr .

Os valores suportados para address_family são atualmente AF_INET e AF_INET6 . Se a cadeia de endereço IP ip_string for inválida, o socket.error será gerado. Observe que exatamente o que é válido depende do valor de address_family e da implementação subjacente de inet_pton() .

Disponibilidade: Unix (talvez nem todas as plataformas). Novo na versão 2.3.

socket. inet_ntop( address_family , packed_ip )

Converta um endereço IP empacotado (uma cadeia de alguns caracteres) em sua representação de string específica da família (por exemplo, '7.10.0.5' ou '5aef:2b::8' ) inet_ntop() é útil quando uma biblioteca ou protocolo de rede retorna um objeto do tipo

struct in_addr (semelhante a inet_ntoa() ) ou struct in6_addr .

Os valores suportados para address_family são atualmente AF_INET e AF_INET6 . Se a string packed_ip não tiver o tamanho correto para a família de endereços especificada, ValueError será gerado. Um socket.error é gerado para erros da chamada para inet_ntop() .

Disponibilidade: Unix (talvez nem todas as plataformas). Novo na versão 2.3.

socket. getdefaulttimeout( )

Retorna o tempo limite padrão em segundos (float) para novos objetos de soquete. Um valor None indica que novos objetos de soquete não têm tempo limite. Quando o módulo de soquete é importado pela primeira vez, o padrão é None .

Novo na versão 2.3.

socket. setdefaulttimeout( tempo limite )

Defina o tempo limite padrão em segundos (float) para novos objetos de soquete. Um valor None indica que novos objetos de soquete não têm tempo limite. Quando o módulo de soquete é importado pela primeira vez, o padrão é None .

Novo na versão 2.3. socket. SocketType

que o type(socket(...)) .

Veja também : Módulo SocketServer

Classes que simplificam a gravação de servidores de rede.

Módulo ssl

Um wrapper TLS / SSL para objetos de soquete.

17.2.1. Objetos de soquete

Objetos de soquete possuem os seguintes métodos. Exceto pelo makefile() eles

correspondem a chamadas do sistema Unix aplicáveis a soquetes. socket. accept ( )

Aceite uma conexão. O soquete deve estar ligado a um endereço e escutar conexões. O valor de retorno é um par (conn, address) que conn é um novo objeto de soquete utilizável para enviar e receber dados na conexão, e endereço é o endereço ligado ao soquete na outra extremidade da conexão.

socket. bind ( endereço )

Amarre o soquete para endereçar . O soquete não deve estar vinculado. (O formato do endereço depende da família de endereços - veja acima.)

Nota : Este método aceitou historicamente um par de parâmetros para endereços

AF_INET vez de apenas uma tupla. Isso nunca foi intencional e não está mais disponível no Python 2.0 e posterior.

socket. close( )

Feche o soquete. Todas as operações futuras no objeto de soquete falharão. A extremidade remota não receberá mais dados (depois que os dados na fila forem liberados). Os soquetes são fechados automaticamente quando são coletados de lixo.

Nota : close() libera o recurso associado a uma conexão, mas não necessariamente fecha a conexão imediatamente. Se você quiser fechar a conexão em tempo hábil, chame shutdown() antes de close() .

socket. connect( endereço )

Conecte-se a um soquete remoto no endereço . (O formato do endereço depende da família de endereços - veja acima.)

AF_INET vez de apenas uma tupla. Isso nunca foi intencional e não está mais disponível no Python 2.0 e posterior.

socket. connect_ex ( endereço )

Como connect(address) , mas retornar um indicador de erro em vez de gerar uma exceção para os erros retornados pela chamada do nível C connect() (outros problemas, como

"host não encontrado", ainda podem gerar exceções). O indicador de erro é 0 se a operação foi bem-sucedida, caso contrário, o valor da variável errno . Isso é útil para

suportar, por exemplo, conexões assíncronas.

Nota : Este método aceitou historicamente um par de parâmetros para endereços

AF_INET vez de apenas uma tupla. Isso nunca foi intencional e não está mais disponível no Python 2.0 e posterior.

socket. fileno ( )

Retorna o descritor de arquivo do soquete (um pequeno inteiro). Isso é útil com select.select() .

No Windows, o inteiro pequeno retornado por este método não pode ser usado onde um descritor de arquivo pode ser usado (como os.fdopen() ). O Unix não tem essa limitação. socket. getpeername( )

Retorna o endereço remoto ao qual o soquete está conectado. Isso é útil para descobrir o número da porta de um soquete IPv4 / v6 remoto, por exemplo. (O formato do endereço retornado depende da família de endereços - veja acima.) Em alguns sistemas, esta função não é suportada.

socket. getsockname( )

Devolve o endereço da própria tomada. Isso é útil para descobrir o número da porta de um soquete IPv4 / v6, por exemplo. (O formato do endereço retornado depende da família de endereços - veja acima.)

socket. getsockopt ( level , optname

[

]

Retorna o valor da opção de socket dada (veja a página man do Unix getsockopt (2) ). As constantes simbólicas necessárias ( SO_* etc.) são definidas neste módulo. Se buflen

estiver ausente, uma opção de número inteiro é assumida e seu valor inteiro é retornado pela função. Se buflen estiver presente, ele especifica o comprimento máximo do buffer usado para receber a opção, e esse buffer é retornado como uma string. Cabe ao chamador decodificar o conteúdo do buffer (consulte a estrutura opcional do módulo struct para obter uma maneira de decodificar estruturas C codificadas como sequências).

socket. ioctl( controle , opção )

O método ioctl() é uma interface limitada para a interface do sistema WSAIoctl. Por favor, consulte a documentação do Win32 para mais informações.

Em outras plataformas, as fcntl.fcntl() genéricas fcntl.fcntl() e fcntl.ioctl() podem ser usadas; eles aceitam um objeto socket como seu primeiro argumento.

Novo na versão 2.6. socket. listen ( backlog )

Ouça as conexões feitas no soquete. O argumento do backlog especifica o número máximo de conexões enfileiradas e deve ser pelo menos 0; o valor máximo é dependente do sistema (geralmente 5), o valor mínimo é forçado para 0.

socket. makefile (

[

[

] ]

Retorna um objeto de arquivo associado ao soquete. (Objetos de arquivo são descritos em objetos de arquivo .) O objeto de arquivo não fecha o soquete explicitamente quando seu método close() é chamado, mas somente remove sua referência ao objeto de soquete, para que o soquete será fechado se não for referenciado de qualquer outro lugar.

O soquete deve estar no modo de bloqueio (não pode ter um tempo limite). O modo opcional e os argumentos bufsize são interpretados da mesma maneira que pela função interna file() .

Nota : No Windows, o objeto semelhante a arquivo criado por makefile() não pode ser usado onde um objeto de arquivo com um descritor de arquivo é esperado, como os argumentos de fluxo de subprocess.Popen() .

socket. recv ( bufsize

[

]

Receber dados do soquete. O valor de retorno é uma string representando os dados recebidos. A quantidade máxima de dados a serem recebidos de uma vez é especificada por bufsize . Veja a página de manual Unix recv (2) para o significado dos argumentos opcionais flags ; o padrão é zero.

Nota : Para melhor correspondência com as realidades de hardware e rede, o valor

de bufsize deve ser uma potência relativamente pequena de 2, por exemplo, 4096. socket. recvfrom ( bufsize

[

]

Receber dados do soquete. O valor de retorno é um par (string, address) onde string é uma string representando os dados recebidos e address é o endereço do socket enviando os dados. Veja a página de manual Unix recv (2) para o significado dos argumentos opcionais flags ; o padrão é zero. (O formato do endereço depende da família de endereços - veja acima.)

socket. recvfrom_into( buffer

[

[

] ]

Receber dados do soquete, gravando-os no buffer em vez de criar uma nova string. O valor de retorno é um par (nbytes, address) onde nbytes é o número de bytes recebidos e endereço é o endereço do socket enviando os dados. Veja a página de manual Unix recv (2) para o significado dos argumentos opcionais flags ; o padrão é zero. (O formato do endereço depende da família de endereços - veja acima.)

Novo na versão 2.5.

socket. recv_into( buffer

[

[

] ]

Receba até bytes nbytes do soquete, armazenando os dados em um buffer em vez de criar uma nova string. Se nbytes não for especificado (ou 0), receba até o tamanho disponível no buffer fornecido. Retorna o número de bytes recebidos. Veja a página de manual Unix recv (2) para o significado dos argumentos opcionais flags ; o padrão é zero.

Novo na versão 2.5.

socket. send ( string

[

]

Envie dados para o soquete. O soquete deve estar conectado a um soquete remoto. O argumento opcional flags tem o mesmo significado que para recv() acima. Retorna o número de bytes enviados. As aplicações são responsáveis por verificar se todos os dados foram enviados; se apenas alguns dados foram transmitidos, o aplicativo precisa tentar entregar os dados restantes. Para mais informações sobre esse conceito, consulte o HOWTO de programação de soquete .

socket. sendall( string

[

]

Envie dados para o soquete. O soquete deve estar conectado a um soquete remoto. O argumento opcional flags tem o mesmo significado que para recv() acima. Ao contrário de send() , esse método continua enviando dados da string até que todos os dados sejam enviados ou ocorra um erro.None é retornado com sucesso. No erro, uma exceção é gerada e não há como determinar a quantidade de dados, se houver, que foram enviados com êxito.

socket. sendto ( string , endereço )

socket. sendto ( string , flags , endereço )

Envie dados para o soquete. O soquete não deve ser conectado a um soquete remoto, pois o soquete de destino é especificado por endereço . O argumento opcional flags tem o mesmo significado que para recv() acima. Retorna o número de bytes enviados. (O formato do endereço depende da família de endereços - veja acima.)

socket. setblocking( flag )

Defina o modo de bloqueio ou não-bloqueio do socket: se o flag for 0, o socket está configurado para não-bloqueio, ou seja, para o modo de bloqueio. Inicialmente, todos os soquetes estão no modo de bloqueio. No modo sem bloqueio, se uma chamada recv()

não encontrar nenhum dado, ou se uma chamada send() não puder descartar imediatamente os dados, uma exceção de error será levantada; no modo de bloqueio, as chamadas bloqueiam até que possam prosseguir. s.setblocking(0) é equivalente a s.settimeout(0.0) ; s.setblocking(1) é equivalente a s.settimeout(None) .

socket. settimeout ( valor )

Definir um tempo limite no bloqueio de operações de soquete. O argumento de valor pode ser um flutuante não-negativo expressando segundos ou None . Se um float for fornecido, as operações subseqüentes do soquete dispararão uma exceção de timeout se o valor do período de tempo limite tiver decorrido antes que a operação seja concluída. Definir um tempo limite de None desativa os tempos limite em operações de soquete. s.settimeout(0.0) é equivalente a s.setblocking(0) ;s.settimeout(None) é equivalente a s.setblocking(1) .

Novo na versão 2.3. socket. gettimeout ( )

Retorna o tempo limite em segundos (flutuante) associado a operações de soquete ou None se nenhum tempo limite estiver definido. Isso reflete a última chamada para setblocking() ou settimeout() .

Novo na versão 2.3.

Algumas notas sobre bloqueio de soquete e tempos limite: Um objeto de soquete pode estar em um dos três modos: bloqueio, não-bloqueio ou tempo limite. Soquetes são sempre criados no modo de bloqueio. No modo de bloqueio, o bloco de operações é concluído ou o sistema retorna um erro (como o tempo limite da conexão). No modo sem bloqueio, as operações falham (com um erro que é, infelizmente, dependente do sistema), se não puderem ser concluídas imediatamente. No modo de tempo limite, as operações falharão se não puderem ser concluídas dentro do tempo limite especificado para o soquete ou se o sistema retornar um erro. O método setblocking() é simplesmente um atalho para certas chamadas settimeout() .

O modo de tempo limite define internamente o soquete no modo sem bloqueio. Os modos de bloqueio e tempo limite são compartilhados entre descritores de arquivos e objetos de soquete que se referem ao mesmo terminal da rede. Uma conseqüência disso é que os objetos de arquivo retornados pelo método makefile() devem ser usados somente quando o soquete estiver no modo de bloqueio; no tempo limite ou operações de arquivo no modo sem bloqueio que não podem ser concluídas imediatamente falhará.

Observe que a connect()operação está sujeita à configuração de tempo limite e, em geral, recomenda-se ligar settimeout()antes de chamar connect()ou passar um parâmetro de tempo limite para create_connection(). A pilha de rede do sistema pode retornar um erro de tempo limite de conexão independente de qualquer configuração de tempo limite do soquete do Python.

socket. setsockopt ( level , optname , value )

Defina o valor da opção de socket fornecida (veja a página de manual do Unix setsockopt (2) ). As constantes simbólicas necessárias são definidas no socketmódulo ( SO_*etc.). O

valor pode ser um inteiro ou uma string representando um buffer. No último caso, cabe ao responsável pela chamada garantir que a sequência contenha os bits apropriados (consulte o módulo interno opcional structpara obter uma maneira de codificar estruturas C como cadeias de caracteres).

socket. shutdown ( como )

Desligue uma ou ambas as metades da conexão. Se como é SHUT_RD, mais

recebimentos não são permitidos. Se como é SHUT_WR, mais envios não são permitidos.

Se como é SHUT_RDWR, mais envia e recebe não são permitidos. Dependendo da

plataforma, desligar uma metade da conexão também pode fechar a metade oposta (por exemplo, no Mac OS X, shutdown(SHUT_WR)não permite mais leituras na outra extremidade da conexão).

Note que não existem métodos read()ou write(); Use recv()e send()sem argumento de sinalizadores em vez disso.

Objetos de soquete também possuem esses atributos (somente leitura) que correspondem aos valores fornecidos ao socketconstrutor.

socket. family A família de tomadas. Novo na versão 2.5. socket. type O tipo de soquete. Novo na versão 2.5. socket. proto O protocolo de soquete. Novo na versão 2.5.

17.2.2. Exemplo

Aqui estão quatro programas de exemplo mínimos usando o protocolo TCP / IP: um servidor que ecoa todos os dados que recebe de volta (atendendo somente a um cliente) e um cliente que os utiliza. Note-se que um servidor deve executar a seqüência socket(), bind(), listen(), accept()(possivelmente repetindo o accept()para atender mais de um cliente), enquanto que um cliente só precisa da sequência socket(), connect(). Observe também que o servidor não sendall()/ recv()no soquete que está escutando, mas no novo socket retornado

por accept().

Os dois primeiros exemplos suportam apenas o IPv4. # Echo server program

import socket

HOST = '' # Symbolic name meaning all available interfaces

PORT = 50007 # Arbitrary non-privileged port

s = socket . socket ( socket . AF_INET , socket . SOCK_STREAM ) s . bind (( HOST , PORT ))

s . listen ( 1 )

conn , addr = s . accept ()

print 'Connected by' , addr

while 1 :

data = conn . recv ( 1024 )

if not data : break

conn . sendall ( data ) conn . close ()

# Echo client program

import socket

HOST = 'daring.cwi.nl' # The remote host

PORT = 50007 # The same port as used by the server

s = socket . socket ( socket . AF_INET , socket . SOCK_STREAM ) s . connect (( HOST , PORT ))

s . sendall ( 'Hello, world' ) data = s . recv ( 1024 )

s . close ()

print 'Received' , repr ( data )

Os próximos dois exemplos são idênticos aos dois acima, mas suportam IPv4 e IPv6. O lado do servidor ouvirá a primeira família de endereços disponível (deve ouvir ambos). Na maioria dos sistemas prontos para IPv6, o IPv6 terá precedência e o servidor poderá não aceitar o tráfego IPv4. O lado do cliente tentará se conectar a todos os endereços retornados como resultado da resolução do nome e enviará tráfego para o primeiro conectado com sucesso.

# Echo server program

import socket

import sys

HOST = None # Symbolic name meaning all available interfaces

PORT = 50007 # Arbitrary non-privileged port

s = None

for res in socket . getaddrinfo ( HOST , PORT , socket . AF_UNSPEC ,

socket . SOCK_STREAM , 0 , socket . AI_PASSIVE ): af , socktype , proto , canonname , sa = res

try :

s = socket . socket ( af , socktype , proto )

except socket . error as msg :

s = None continue

try :

s . bind ( sa ) s . listen ( 1 )

except socket . error as msg : s . close () s = None continue break if s is None :

print 'could not open socket'

sys . exit ( 1 )

conn , addr = s . accept ()

print 'Connected by' , addr

while 1 :

data = conn . recv ( 1024 )

if not data : break

conn . send ( data ) conn . close ()

# Echo client program

import socket

import sys

HOST = 'daring.cwi.nl' # The remote host

PORT = 50007 # The same port as used by the server

s = None

for res in socket . getaddrinfo ( HOST , PORT , socket . AF_UNSPEC , socket . SOCK_STREAM af , socktype , proto , canonname , sa = res

try :

s = socket . socket ( af , socktype , proto )

except socket . error as msg :

s = None continue

try :

s . connect ( sa )

except socket . error as msg :

s . close () s = None continue break

if s is None :

print 'could not open socket'

sys . exit ( 1 )

s . sendall ( 'Hello, world' ) data = s . recv ( 1024 )

s . close ()

print 'Received' , repr ( data )

O último exemplo mostra como escrever um sniffer de rede muito simples com soquetes brutos no Windows. O exemplo requer privilégios de administrador para modificar a interface:

import socket

# the public network interface

HOST = socket . gethostbyname ( socket . gethostname ())

# create a raw socket and bind it to the public interface

s = socket . socket ( socket . AF_INET , socket . SOCK_RAW , socket . IPPROTO_IP ) s . bind (( HOST , 0 ))

# Include IP headers

s . setsockopt ( socket . IPPROTO_IP , socket . IP_HDRINCL , 1 )

# receive all packages

s . ioctl ( socket . SIO_RCVALL , socket . RCVALL_ON )

# receive a package

print s . recvfrom ( 65565 )

# disabled promiscuous mode

s . ioctl ( socket . SIO_RCVALL , socket . RCVALL_OFF )

Executar um exemplo várias vezes com um atraso muito pequeno entre as execuções pode levar a esse erro:

socket . error : [ Errno 98 ] Address already in use

Isso ocorre porque a execução anterior deixou o soquete em um TIME_WAITestado e não pode ser reutilizada imediatamente.

Há um socketsinalizador para definir, a fim de evitar isso socket.SO_REUSEADDR:

s = socket . socket ( socket . AF_INET , socket . SOCK_STREAM ) s . setsockopt ( socket . SOL_SOCKET , socket . SO_REUSEADDR , 1 ) s . bind (( HOST , PORT ))

o SO_REUSEADDRsinalizador diz ao kernel para reutilizar um soquete local no TIME_WAITestado,