socket — socket-moduuli

Tämä moduuli tarjoaa pääsyn BSD-socket-rajapintaan.

Ero CPythoniin

Tehokkuuden ja yhdenmukaisuuden vuoksi socket-objektit toteuttavat MicroPythonissa suoraan stream-rajapinnan (tiedostomaisen). CPythonissa socket on muunnettava tiedostomaiseksi objektiksi makefile()-metodilla. MicroPython tukee tätä metodia edelleen (mutta se ei tee mitään), joten kun yhteensopivuus CPythonin kanssa on tärkeää, käytä sitä varmuuden vuoksi.

Socket-osoitteen muoto(t)

socket-moduulin natiivi socket-osoitemuoto on läpinäkymätön tietotyyppi, jonka getaddrinfo()-funktio palauttaa ja jota on käytettävä tekstimuotoisen osoitteen (mukaan lukien numeeriset osoitteet) resolvointiin:

sockaddr = socket.getaddrinfo('www.micropython.org', 80)[0][-1]
# You must use getaddrinfo() even for numeric addresses
sockaddr = socket.getaddrinfo('127.0.0.1', 80)[0][-1]
# Now you can use that address
sock.connect(sockaddr)

getaddrinfo()-funktion käyttö on tehokkain (sekä muistin että prosessoritehon kannalta) ja siirrettävin tapa työskennellä osoitteiden kanssa.

socket-moduuli tarjoaa myös CPythonin kanssa yhteensopivan tavan määrittää osoitteita käyttäen monikoita, kuten alla kuvataan. OpenMV Camissa socket-moduuli on sisäänrakennettu; numeeriset osoitteet voidaan antaa suoraan monikkomuodossa, mutta verkkotunnukset on ensin resolvoitava funktiolla getaddrinfo().

Yhteenvetona:

• Käytä aina getaddrinfo()-funktiota isäntänimien resolvointiin.

• Alla kuvattuja monikko-osoitteita voidaan käyttää oikotienä numeerisille osoitteille, nopeisiin kokeiluihin ja interaktiiviseen käyttöön.

Monikko-osoitemuoto socket-moduulille:

• IPv4: (ipv4_address, port), jossa ipv4_address on merkkijono, joka sisältää pistemerkinnällä esitetyn numeerisen IPv4-osoitteen, esim. "8.8.8.8", ja port on kokonaisluku porttinumero välillä 1-65535. Verkkotunnuksia ei hyväksytä ipv4_address-arvoksi; resolvoi ne ensin funktiolla getaddrinfo().

• IPv6: (ipv6_address, port, flowinfo, scopeid), jossa ipv6_address on merkkijono, joka sisältää kaksoispistemerkinnällä esitetyn numeerisen IPv6-osoitteen, esim. "2001:db8::1", ja port on kokonaisluku porttinumero välillä 1-65535. flowinfo on oltava 0. scopeid on rajapinnan laajuustunniste link-local-osoitteille. Verkkotunnuksia ei hyväksytä ipv6_address-arvoksi; resolvoi ne ensin funktiolla getaddrinfo().

Funktiot

socket.getaddrinfo(host: str, port: int, af: int = 0, type: int = 0, proto: int = 0, flags: int = 0, /) → List[Tuple]

Muuntaa host/port-argumentin 5-monikoiden sekvenssiksi, joka sisältää kaikki tarvittavat argumentit kyseiseen palveluun yhdistetyn socketin luomiseksi. Argumentteja af, type ja proto (joilla on sama merkitys kuin socket-funktiolle) voidaan käyttää suodattamaan, minkätyyppiset osoitteet palautetaan. Jos parametria ei ole määritetty tai se on nolla, kaikki osoiteyhdistelmät voidaan palauttaa (mikä edellyttää suodatusta käyttäjän puolella).

Tuloksena saatavalla 5-monikoiden listalla on seuraava rakenne:

(family, type, proto, canonname, sockaddr)

Seuraava esimerkki näyttää, miten yhdistetään annettuun URL-osoitteeseen:

s = socket.socket()
# This assumes that if "type" is not specified, an address for
# SOCK_STREAM will be returned, which may be not true
s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])

Suositeltu suodatusparametrien käyttö:

s = socket.socket()
# Guaranteed to return an address which can be connect'ed to for
# stream operation.
s.connect(socket.getaddrinfo('www.micropython.org', 80, 0, SOCK_STREAM)[0][-1])

Ero CPythoniin

CPython nostaa socket.gaierror-poikkeuksen (OSError-aliluokka), jos tässä funktiossa tapahtuu virhe. MicroPythonilla ei ole socket.gaierror-poikkeusta, vaan se nostaa OSError-poikkeuksen suoraan. Huomaa, että getaddrinfo()-funktion virhenumerot muodostavat erillisen nimiavaruuden eivätkä välttämättä täsmää errno-moduulin virhenumeroiden kanssa. getaddrinfo()-virheiden erottamiseksi ne esitetään negatiivisina lukuina, kun taas tavalliset järjestelmävirheet ovat positiivisia lukuja (virhenumerot ovat saatavilla poikkeusobjektin e.args[0]-ominaisuuden kautta). Negatiivisten arvojen käyttö on väliaikainen yksityiskohta, joka voi muuttua tulevaisuudessa.

socket.inet_ntop(af: int, bin_addr: bytes) → str

Muuntaa annetun osoiteperheen af binäärisen verkko-osoitteen bin_addr tekstimuotoiseksi esitykseksi:

>>> socket.inet_ntop(socket.AF_INET, b"\x7f\0\0\1")
'127.0.0.1'

socket.inet_pton(af: int, txt_addr: str) → bytes

Muuntaa annetun osoiteperheen af tekstimuotoisen verkko-osoitteen txt_addr binääriseksi esitykseksi:

>>> socket.inet_pton(socket.AF_INET, "1.2.3.4")
b'\x01\x02\x03\x04'

Vakiot

socket.AF_INET: int

IPv4-osoiteperhe.

socket.AF_INET6: int

IPv6-osoiteperhe.

socket.SOCK_STREAM: int

Stream (TCP) -socket-tyyppi.

socket.SOCK_DGRAM: int

Datagrammi (UDP) -socket-tyyppi.

socket.SOCK_RAW: int

Raaka socket-tyyppi.

socket.IPPROTO_IP: int

IP-protokollataso. Käytetään level-argumenttina metodissa setsockopt() yhdessä IP_*-vaihtoehtojen kanssa.

socket.IPPROTO_TCP: int

TCP-protokolla. Sinun ei tarvitse välittää tätä socket-funktiolle (SOCK_STREAM-socket-tyyppi valitsee sen automaattisesti); sen ainoa todellinen käyttö on level-argumenttina metodissa setsockopt() yhdessä TCP_*-vaihtoehtojen kanssa.

socket.SOL_SOCKET: int

Socket-vaihtoehtotaso. Käytetään level-argumenttina metodissa setsockopt() yhdessä SO_*-vaihtoehtojen kanssa.

socket.SO_REUSEADDR: int

Salli socketin sitoutua osoitteeseen/porttiin, joka on edelleen TIME_WAIT-tilassa.

socket.SO_BROADCAST: int

Salli datagrammien lähettäminen yleislähetysosoitteeseen.

socket.SO_KEEPALIVE: int

Ota käyttöön keep-alive-koettimien jaksottainen lähetys yhdistetyssä socketissa.

socket.SO_SNDTIMEO: int

Lähetyksen aikakatkaisu millisekunteina, välitetään value-argumenttina metodille setsockopt().

socket.SO_RCVTIMEO: int

Vastaanoton aikakatkaisu millisekunteina, välitetään value-argumenttina metodille setsockopt().

socket.IP_ADD_MEMBERSHIP: int

Liity multicast-ryhmään. IPPROTO_IP-tason setsockopt()-vaihtoehto.

socket.IP_DROP_MEMBERSHIP: int

Poistu multicast-ryhmästä. IPPROTO_IP-tason setsockopt()-vaihtoehto.

socket.TCP_NODELAY: int

Poista Naglen algoritmi käytöstä. IPPROTO_TCP-tason setsockopt()-vaihtoehto.

socket.MSG_PEEK: int

Metodeille recv() / recvfrom(): palauta data poistamatta sitä syötejonosta.

socket.MSG_DONTWAIT: int

Metodeille recv() / recvfrom(): suorita operaatio ei-estävässä tilassa.

Luokat

class socket.socket(af: int = AF_INET, type: int = SOCK_STREAM, proto: int = IPPROTO_TCP, /)

Luo uusi socket käyttäen annettua osoiteperhettä, socket-tyyppiä ja protokollanumeroa. proto-arvon määrittäminen ei useimmissa tapauksissa ole tarpeellista (eikä suositeltavaa); type-argumentti valitsee tarvittavan protokollan automaattisesti:

# Create STREAM TCP socket
socket(AF_INET, SOCK_STREAM)
# Create DGRAM UDP socket
socket(AF_INET, SOCK_DGRAM)

close() → None

Merkitse socket suljetuksi ja vapauta kaikki resurssit. Kun näin tapahtuu, kaikki socket-objektin tulevat operaatiot epäonnistuvat. Etäpää saa EOF-merkinnän, jos protokolla tukee sitä.

Socketit suljetaan automaattisesti, kun ne kerätään roskienkeräyksessä, mutta on suositeltavaa close()-sulkea ne nimenomaisesti heti, kun olet lopettanut niiden käytön.

bind(address: Any) → None

Sido socket osoitteeseen address. Socket ei saa olla jo sidottu.

listen(backlog: int = 2) → None

Salli palvelimen hyväksyä yhteyksiä. Jos backlog on määritetty, sen on oltava vähintään 0 (jos se on pienempi, se asetetaan arvoon 0); se määrittää hyväksymättömien yhteyksien määrän, jonka järjestelmä sallii ennen kuin se hylkää uudet yhteydet. Jos sitä ei ole määritetty, valitaan oletusarvoisesti järkevä arvo.

accept() → Tuple['socket', Tuple]

Hyväksy yhteys. Socketin on oltava sidottu osoitteeseen ja kuunneltava yhteyksiä. Paluuarvo on pari (conn, address), jossa conn on uusi socket-objekti, jota voidaan käyttää datan lähettämiseen ja vastaanottamiseen yhteydellä, ja address on yhteyden toisessa päässä socketiin sidottu osoite.

connect(address: Any) → None

Yhdistä etäsocketiin osoitteessa address.

send(bytes: bytes) → int

Lähetä dataa socketiin. Socketin on oltava yhdistetty etäsocketiin. Palauttaa lähetettyjen tavujen määrän, joka voi olla pienempi kuin datan pituus (”short write”).

sendall(bytes: bytes) → None

Lähetä kaikki data socketiin. Socketin on oltava yhdistetty etäsocketiin. Toisin kuin send(), tämä metodi yrittää lähettää kaiken datan lähettämällä sen lohko lohkolta peräkkäin.

Tämän metodin toiminta ei-estävissä socketeissa on määrittelemätön. Tämän vuoksi MicroPythonissa on suositeltavaa käyttää sen sijaan write()-metodia, jolla on sama ”ei short write -kirjoituksia” -käytäntö estäville socketeille ja joka palauttaa lähetettyjen tavujen määrän ei-estävissä socketeissa.

recv(bufsize: int, flags: int = 0) → bytes

Vastaanota dataa socketista. Paluuarvo on tavuobjekti, joka edustaa vastaanotettua dataa. Kerralla vastaanotettavan datan enimmäismäärä määritetään bufsize-arvolla.

Valinnainen flags-argumentti on viestilippujen (MSG_PEEK, MSG_DONTWAIT) bittikohtainen OR, joilla on sama merkitys kuin CPythonissa.

sendto(bytes: bytes, address: Any) → int

Lähetä dataa socketiin. Socketin ei pitäisi olla yhdistetty etäsocketiin, koska kohdesocket määritetään address-argumentilla.

recvfrom(bufsize: int, flags: int = 0) → Tuple[bytes, Tuple]

Vastaanota dataa socketista. Paluuarvo on pari (bytes, address), jossa bytes on tavuobjekti, joka edustaa vastaanotettua dataa, ja address on dataa lähettävän socketin osoite.

Katso recv()-funktiosta selitys valinnaiselle flags-argumentille.

setsockopt(level: int, optname: int, value: int | bytes) → None

Aseta annetun socket-vaihtoehdon arvo. Tarvittavat symboliset vakiot on määritelty socket-moduulissa (SO_* jne.). value voi olla kokonaisluku tai puskuria edustava tavumainen objekti.

settimeout(value: float | None) → None

Aseta aikakatkaisu estäville socket-operaatioille. value-argumentti voi olla ei-negatiivinen liukuluku, joka ilmaisee sekunteja, tai None. Jos annetaan nollasta poikkeava arvo, myöhemmät socket-operaatiot nostavat OSError-poikkeuksen, jos aikakatkaisuaika on kulunut ennen kuin operaatio on valmistunut. Jos annetaan nolla, socket asetetaan ei-estävään tilaan. Jos annetaan None, socket asetetaan estävään tilaan.

Siirrettävä ja yleinen vaihtoehto on käyttää select.poll-objektia. Tämä mahdollistaa useiden objektien odottamisen samanaikaisesti (eikä vain socketien, vaan yleisten stream-objektien, jotka tukevat pollausta). Esimerkki:

# Instead of:
s.settimeout(1.0)  # time in seconds
s.read(10)  # may timeout

# Use:
poller = select.poll()
poller.register(s, select.POLLIN)
res = poller.poll(1000)  # time in milliseconds
if not res:
    # s is still not ready for input, i.e. operation timed out

Ero CPythoniin

CPython nostaa socket.timeout-poikkeuksen aikakatkaisun tapahtuessa; se on OSError-aliluokka. MicroPython nostaa sen sijaan OSError-poikkeuksen suoraan. Jos käytät except OSError: poikkeuksen kiinniottoon, koodisi toimii sekä MicroPythonissa että CPythonissa.

setblocking(flag: bool) → None

Aseta socketin estävä tai ei-estävä tila: jos flag on false, socket asetetaan ei-estävään, muutoin estävään tilaan.

Tämä metodi on lyhennys tietyille settimeout()-kutsuille:

• sock.setblocking(True) vastaa kutsua sock.settimeout(None)

• sock.setblocking(False) vastaa kutsua sock.settimeout(0)

makefile(mode: str = 'rb', buffering: int = 0, /) → Any

Palauta socketiin liittyvä tiedosto-objekti. Tarkka palautettava tyyppi riippuu makefile()-funktiolle annetuista argumenteista. Tuki rajoittuu vain binääritiloihin (’rb’, ’wb’ ja ’rwb’). CPythonin argumentteja encoding, errors ja newline ei tueta.

Ero CPythoniin

Koska MicroPython ei tue puskuroituja streameja, buffering-parametrin arvot ohitetaan ja käsitellään ikään kuin se olisi 0 (puskuroimaton).

Ero CPythoniin

makefile()-funktion palauttaman tiedosto-objektin sulkeminen sulkee MYÖS alkuperäisen socketin.

read(size: int | None = None) → bytes

Lue socketista enintään size tavua. Palauttaa tavuobjektin. Jos size-arvoa ei anneta, se lukee kaiken socketista saatavilla olevan datan EOF:ään asti; sellaisenaan metodi ei palaa ennen kuin socket on suljettu. Tämä funktio yrittää lukea niin paljon dataa kuin on pyydetty (ei ”short read” -lukuja). Tämä ei kuitenkaan ehkä ole mahdollista ei-estävällä socketilla, jolloin palautetaan vähemmän dataa.

readinto(buf: bytearray | memoryview, nbytes: int | None = None) → int

Lue tavuja buf-puskuriin. Jos nbytes on määritetty, lue enintään niin monta tavua. Muutoin lue enintään len(buf) tavua. Aivan kuten read(), tämä metodi noudattaa ”ei short read -lukuja” -käytäntöä.

Paluuarvo: luettujen ja buf-puskuriin tallennettujen tavujen määrä.

readline() → bytes

Lue rivi, joka päättyy rivinvaihtomerkkiin.

Paluuarvo: luettu rivi.

write(buf: bytes) → int

Kirjoita tavupuskuri socketiin. Tämä funktio yrittää kirjoittaa kaiken datan socketiin (ei ”short write” -kirjoituksia). Tämä ei kuitenkaan ehkä ole mahdollista ei-estävällä socketilla, jolloin palautettu arvo on pienempi kuin buf-puskurin pituus.

Paluuarvo: kirjoitettujen tavujen määrä.

Muista

MicroPython ei toteuta socket.error-poikkeusta. CPythonilla on vanhentunut socket.error-poikkeus, joka on OSError-poikkeuksen alias; käytä MicroPythonissa OSError-poikkeusta suoraan socketiin liittyvien virheiden kiinniottoon.