1# Wrapper module for _socket, providing some additional facilities 2# implemented in Python. 3 4"""\ 5This module provides socket operations and some related functions. 6On Unix, it supports IP (Internet Protocol) and Unix domain sockets. 7On other systems, it only supports IP. Functions specific for a 8socket are available as methods of the socket object. 9 10Functions: 11 12socket() -- create a new socket object 13socketpair() -- create a pair of new socket objects [*] 14fromfd() -- create a socket object from an open file descriptor [*] 15send_fds() -- Send file descriptor to the socket. 16recv_fds() -- Recieve file descriptors from the socket. 17fromshare() -- create a socket object from data received from socket.share() [*] 18gethostname() -- return the current hostname 19gethostbyname() -- map a hostname to its IP number 20gethostbyaddr() -- map an IP number or hostname to DNS info 21getservbyname() -- map a service name and a protocol name to a port number 22getprotobyname() -- map a protocol name (e.g. 'tcp') to a number 23ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order 24htons(), htonl() -- convert 16, 32 bit int from host to network byte order 25inet_aton() -- convert IP addr string (123.45.67.89) to 32-bit packed format 26inet_ntoa() -- convert 32-bit packed format IP to string (123.45.67.89) 27socket.getdefaulttimeout() -- get the default timeout value 28socket.setdefaulttimeout() -- set the default timeout value 29create_connection() -- connects to an address, with an optional timeout and 30 optional source address. 31 32 [*] not available on all platforms! 33 34Special objects: 35 36SocketType -- type object for socket objects 37error -- exception raised for I/O errors 38has_ipv6 -- boolean value indicating if IPv6 is supported 39 40IntEnum constants: 41 42AF_INET, AF_UNIX -- socket domains (first argument to socket() call) 43SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument) 44 45Integer constants: 46 47Many other constants may be defined; these may be used in calls to 48the setsockopt() and getsockopt() methods. 49""" 50 51import _socket 52from _socket import * 53 54import os, sys, io, selectors 55from enum import IntEnum, IntFlag 56 57try: 58 import errno 59except ImportError: 60 errno = None 61EBADF = getattr(errno, 'EBADF', 9) 62EAGAIN = getattr(errno, 'EAGAIN', 11) 63EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11) 64 65__all__ = ["fromfd", "getfqdn", "create_connection", "create_server", 66 "has_dualstack_ipv6", "AddressFamily", "SocketKind"] 67__all__.extend(os._get_exports_list(_socket)) 68 69# Set up the socket.AF_* socket.SOCK_* constants as members of IntEnums for 70# nicer string representations. 71# Note that _socket only knows about the integer values. The public interface 72# in this module understands the enums and translates them back from integers 73# where needed (e.g. .family property of a socket object). 74 75IntEnum._convert_( 76 'AddressFamily', 77 __name__, 78 lambda C: C.isupper() and C.startswith('AF_')) 79 80IntEnum._convert_( 81 'SocketKind', 82 __name__, 83 lambda C: C.isupper() and C.startswith('SOCK_')) 84 85IntFlag._convert_( 86 'MsgFlag', 87 __name__, 88 lambda C: C.isupper() and C.startswith('MSG_')) 89 90IntFlag._convert_( 91 'AddressInfo', 92 __name__, 93 lambda C: C.isupper() and C.startswith('AI_')) 94 95_LOCALHOST = '127.0.0.1' 96_LOCALHOST_V6 = '::1' 97 98 99def _intenum_converter(value, enum_klass): 100 """Convert a numeric family value to an IntEnum member. 101 102 If it's not a known member, return the numeric value itself. 103 """ 104 try: 105 return enum_klass(value) 106 except ValueError: 107 return value 108 109 110# WSA error codes 111if sys.platform.lower().startswith("win"): 112 errorTab = {} 113 errorTab[6] = "Specified event object handle is invalid." 114 errorTab[8] = "Insufficient memory available." 115 errorTab[87] = "One or more parameters are invalid." 116 errorTab[995] = "Overlapped operation aborted." 117 errorTab[996] = "Overlapped I/O event object not in signaled state." 118 errorTab[997] = "Overlapped operation will complete later." 119 errorTab[10004] = "The operation was interrupted." 120 errorTab[10009] = "A bad file handle was passed." 121 errorTab[10013] = "Permission denied." 122 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT 123 errorTab[10022] = "An invalid operation was attempted." 124 errorTab[10024] = "Too many open files." 125 errorTab[10035] = "The socket operation would block" 126 errorTab[10036] = "A blocking operation is already in progress." 127 errorTab[10037] = "Operation already in progress." 128 errorTab[10038] = "Socket operation on nonsocket." 129 errorTab[10039] = "Destination address required." 130 errorTab[10040] = "Message too long." 131 errorTab[10041] = "Protocol wrong type for socket." 132 errorTab[10042] = "Bad protocol option." 133 errorTab[10043] = "Protocol not supported." 134 errorTab[10044] = "Socket type not supported." 135 errorTab[10045] = "Operation not supported." 136 errorTab[10046] = "Protocol family not supported." 137 errorTab[10047] = "Address family not supported by protocol family." 138 errorTab[10048] = "The network address is in use." 139 errorTab[10049] = "Cannot assign requested address." 140 errorTab[10050] = "Network is down." 141 errorTab[10051] = "Network is unreachable." 142 errorTab[10052] = "Network dropped connection on reset." 143 errorTab[10053] = "Software caused connection abort." 144 errorTab[10054] = "The connection has been reset." 145 errorTab[10055] = "No buffer space available." 146 errorTab[10056] = "Socket is already connected." 147 errorTab[10057] = "Socket is not connected." 148 errorTab[10058] = "The network has been shut down." 149 errorTab[10059] = "Too many references." 150 errorTab[10060] = "The operation timed out." 151 errorTab[10061] = "Connection refused." 152 errorTab[10062] = "Cannot translate name." 153 errorTab[10063] = "The name is too long." 154 errorTab[10064] = "The host is down." 155 errorTab[10065] = "The host is unreachable." 156 errorTab[10066] = "Directory not empty." 157 errorTab[10067] = "Too many processes." 158 errorTab[10068] = "User quota exceeded." 159 errorTab[10069] = "Disk quota exceeded." 160 errorTab[10070] = "Stale file handle reference." 161 errorTab[10071] = "Item is remote." 162 errorTab[10091] = "Network subsystem is unavailable." 163 errorTab[10092] = "Winsock.dll version out of range." 164 errorTab[10093] = "Successful WSAStartup not yet performed." 165 errorTab[10101] = "Graceful shutdown in progress." 166 errorTab[10102] = "No more results from WSALookupServiceNext." 167 errorTab[10103] = "Call has been canceled." 168 errorTab[10104] = "Procedure call table is invalid." 169 errorTab[10105] = "Service provider is invalid." 170 errorTab[10106] = "Service provider failed to initialize." 171 errorTab[10107] = "System call failure." 172 errorTab[10108] = "Service not found." 173 errorTab[10109] = "Class type not found." 174 errorTab[10110] = "No more results from WSALookupServiceNext." 175 errorTab[10111] = "Call was canceled." 176 errorTab[10112] = "Database query was refused." 177 errorTab[11001] = "Host not found." 178 errorTab[11002] = "Nonauthoritative host not found." 179 errorTab[11003] = "This is a nonrecoverable error." 180 errorTab[11004] = "Valid name, no data record requested type." 181 errorTab[11005] = "QoS receivers." 182 errorTab[11006] = "QoS senders." 183 errorTab[11007] = "No QoS senders." 184 errorTab[11008] = "QoS no receivers." 185 errorTab[11009] = "QoS request confirmed." 186 errorTab[11010] = "QoS admission error." 187 errorTab[11011] = "QoS policy failure." 188 errorTab[11012] = "QoS bad style." 189 errorTab[11013] = "QoS bad object." 190 errorTab[11014] = "QoS traffic control error." 191 errorTab[11015] = "QoS generic error." 192 errorTab[11016] = "QoS service type error." 193 errorTab[11017] = "QoS flowspec error." 194 errorTab[11018] = "Invalid QoS provider buffer." 195 errorTab[11019] = "Invalid QoS filter style." 196 errorTab[11020] = "Invalid QoS filter style." 197 errorTab[11021] = "Incorrect QoS filter count." 198 errorTab[11022] = "Invalid QoS object length." 199 errorTab[11023] = "Incorrect QoS flow count." 200 errorTab[11024] = "Unrecognized QoS object." 201 errorTab[11025] = "Invalid QoS policy object." 202 errorTab[11026] = "Invalid QoS flow descriptor." 203 errorTab[11027] = "Invalid QoS provider-specific flowspec." 204 errorTab[11028] = "Invalid QoS provider-specific filterspec." 205 errorTab[11029] = "Invalid QoS shape discard mode object." 206 errorTab[11030] = "Invalid QoS shaping rate object." 207 errorTab[11031] = "Reserved policy QoS element type." 208 __all__.append("errorTab") 209 210 211class _GiveupOnSendfile(Exception): pass 212 213 214class socket(_socket.socket): 215 216 """A subclass of _socket.socket adding the makefile() method.""" 217 218 __slots__ = ["__weakref__", "_io_refs", "_closed"] 219 220 def __init__(self, family=-1, type=-1, proto=-1, fileno=None): 221 # For user code address family and type values are IntEnum members, but 222 # for the underlying _socket.socket they're just integers. The 223 # constructor of _socket.socket converts the given argument to an 224 # integer automatically. 225 if fileno is None: 226 if family == -1: 227 family = AF_INET 228 if type == -1: 229 type = SOCK_STREAM 230 if proto == -1: 231 proto = 0 232 _socket.socket.__init__(self, family, type, proto, fileno) 233 self._io_refs = 0 234 self._closed = False 235 236 def __enter__(self): 237 return self 238 239 def __exit__(self, *args): 240 if not self._closed: 241 self.close() 242 243 def __repr__(self): 244 """Wrap __repr__() to reveal the real class name and socket 245 address(es). 246 """ 247 closed = getattr(self, '_closed', False) 248 s = "<%s.%s%s fd=%i, family=%s, type=%s, proto=%i" \ 249 % (self.__class__.__module__, 250 self.__class__.__qualname__, 251 " [closed]" if closed else "", 252 self.fileno(), 253 self.family, 254 self.type, 255 self.proto) 256 if not closed: 257 try: 258 laddr = self.getsockname() 259 if laddr: 260 s += ", laddr=%s" % str(laddr) 261 except error: 262 pass 263 try: 264 raddr = self.getpeername() 265 if raddr: 266 s += ", raddr=%s" % str(raddr) 267 except error: 268 pass 269 s += '>' 270 return s 271 272 def __getstate__(self): 273 raise TypeError(f"cannot pickle {self.__class__.__name__!r} object") 274 275 def dup(self): 276 """dup() -> socket object 277 278 Duplicate the socket. Return a new socket object connected to the same 279 system resource. The new socket is non-inheritable. 280 """ 281 fd = dup(self.fileno()) 282 sock = self.__class__(self.family, self.type, self.proto, fileno=fd) 283 sock.settimeout(self.gettimeout()) 284 return sock 285 286 def accept(self): 287 """accept() -> (socket object, address info) 288 289 Wait for an incoming connection. Return a new socket 290 representing the connection, and the address of the client. 291 For IP sockets, the address info is a pair (hostaddr, port). 292 """ 293 fd, addr = self._accept() 294 sock = socket(self.family, self.type, self.proto, fileno=fd) 295 # Issue #7995: if no default timeout is set and the listening 296 # socket had a (non-zero) timeout, force the new socket in blocking 297 # mode to override platform-specific socket flags inheritance. 298 if getdefaulttimeout() is None and self.gettimeout(): 299 sock.setblocking(True) 300 return sock, addr 301 302 def makefile(self, mode="r", buffering=None, *, 303 encoding=None, errors=None, newline=None): 304 """makefile(...) -> an I/O stream connected to the socket 305 306 The arguments are as for io.open() after the filename, except the only 307 supported mode values are 'r' (default), 'w' and 'b'. 308 """ 309 # XXX refactor to share code? 310 if not set(mode) <= {"r", "w", "b"}: 311 raise ValueError("invalid mode %r (only r, w, b allowed)" % (mode,)) 312 writing = "w" in mode 313 reading = "r" in mode or not writing 314 assert reading or writing 315 binary = "b" in mode 316 rawmode = "" 317 if reading: 318 rawmode += "r" 319 if writing: 320 rawmode += "w" 321 raw = SocketIO(self, rawmode) 322 self._io_refs += 1 323 if buffering is None: 324 buffering = -1 325 if buffering < 0: 326 buffering = io.DEFAULT_BUFFER_SIZE 327 if buffering == 0: 328 if not binary: 329 raise ValueError("unbuffered streams must be binary") 330 return raw 331 if reading and writing: 332 buffer = io.BufferedRWPair(raw, raw, buffering) 333 elif reading: 334 buffer = io.BufferedReader(raw, buffering) 335 else: 336 assert writing 337 buffer = io.BufferedWriter(raw, buffering) 338 if binary: 339 return buffer 340 text = io.TextIOWrapper(buffer, encoding, errors, newline) 341 text.mode = mode 342 return text 343 344 if hasattr(os, 'sendfile'): 345 346 def _sendfile_use_sendfile(self, file, offset=0, count=None): 347 self._check_sendfile_params(file, offset, count) 348 sockno = self.fileno() 349 try: 350 fileno = file.fileno() 351 except (AttributeError, io.UnsupportedOperation) as err: 352 raise _GiveupOnSendfile(err) # not a regular file 353 try: 354 fsize = os.fstat(fileno).st_size 355 except OSError as err: 356 raise _GiveupOnSendfile(err) # not a regular file 357 if not fsize: 358 return 0 # empty file 359 # Truncate to 1GiB to avoid OverflowError, see bpo-38319. 360 blocksize = min(count or fsize, 2 ** 30) 361 timeout = self.gettimeout() 362 if timeout == 0: 363 raise ValueError("non-blocking sockets are not supported") 364 # poll/select have the advantage of not requiring any 365 # extra file descriptor, contrarily to epoll/kqueue 366 # (also, they require a single syscall). 367 if hasattr(selectors, 'PollSelector'): 368 selector = selectors.PollSelector() 369 else: 370 selector = selectors.SelectSelector() 371 selector.register(sockno, selectors.EVENT_WRITE) 372 373 total_sent = 0 374 # localize variable access to minimize overhead 375 selector_select = selector.select 376 os_sendfile = os.sendfile 377 try: 378 while True: 379 if timeout and not selector_select(timeout): 380 raise _socket.timeout('timed out') 381 if count: 382 blocksize = count - total_sent 383 if blocksize <= 0: 384 break 385 try: 386 sent = os_sendfile(sockno, fileno, offset, blocksize) 387 except BlockingIOError: 388 if not timeout: 389 # Block until the socket is ready to send some 390 # data; avoids hogging CPU resources. 391 selector_select() 392 continue 393 except OSError as err: 394 if total_sent == 0: 395 # We can get here for different reasons, the main 396 # one being 'file' is not a regular mmap(2)-like 397 # file, in which case we'll fall back on using 398 # plain send(). 399 raise _GiveupOnSendfile(err) 400 raise err from None 401 else: 402 if sent == 0: 403 break # EOF 404 offset += sent 405 total_sent += sent 406 return total_sent 407 finally: 408 if total_sent > 0 and hasattr(file, 'seek'): 409 file.seek(offset) 410 else: 411 def _sendfile_use_sendfile(self, file, offset=0, count=None): 412 raise _GiveupOnSendfile( 413 "os.sendfile() not available on this platform") 414 415 def _sendfile_use_send(self, file, offset=0, count=None): 416 self._check_sendfile_params(file, offset, count) 417 if self.gettimeout() == 0: 418 raise ValueError("non-blocking sockets are not supported") 419 if offset: 420 file.seek(offset) 421 blocksize = min(count, 8192) if count else 8192 422 total_sent = 0 423 # localize variable access to minimize overhead 424 file_read = file.read 425 sock_send = self.send 426 try: 427 while True: 428 if count: 429 blocksize = min(count - total_sent, blocksize) 430 if blocksize <= 0: 431 break 432 data = memoryview(file_read(blocksize)) 433 if not data: 434 break # EOF 435 while True: 436 try: 437 sent = sock_send(data) 438 except BlockingIOError: 439 continue 440 else: 441 total_sent += sent 442 if sent < len(data): 443 data = data[sent:] 444 else: 445 break 446 return total_sent 447 finally: 448 if total_sent > 0 and hasattr(file, 'seek'): 449 file.seek(offset + total_sent) 450 451 def _check_sendfile_params(self, file, offset, count): 452 if 'b' not in getattr(file, 'mode', 'b'): 453 raise ValueError("file should be opened in binary mode") 454 if not self.type & SOCK_STREAM: 455 raise ValueError("only SOCK_STREAM type sockets are supported") 456 if count is not None: 457 if not isinstance(count, int): 458 raise TypeError( 459 "count must be a positive integer (got {!r})".format(count)) 460 if count <= 0: 461 raise ValueError( 462 "count must be a positive integer (got {!r})".format(count)) 463 464 def sendfile(self, file, offset=0, count=None): 465 """sendfile(file[, offset[, count]]) -> sent 466 467 Send a file until EOF is reached by using high-performance 468 os.sendfile() and return the total number of bytes which 469 were sent. 470 *file* must be a regular file object opened in binary mode. 471 If os.sendfile() is not available (e.g. Windows) or file is 472 not a regular file socket.send() will be used instead. 473 *offset* tells from where to start reading the file. 474 If specified, *count* is the total number of bytes to transmit 475 as opposed to sending the file until EOF is reached. 476 File position is updated on return or also in case of error in 477 which case file.tell() can be used to figure out the number of 478 bytes which were sent. 479 The socket must be of SOCK_STREAM type. 480 Non-blocking sockets are not supported. 481 """ 482 try: 483 return self._sendfile_use_sendfile(file, offset, count) 484 except _GiveupOnSendfile: 485 return self._sendfile_use_send(file, offset, count) 486 487 def _decref_socketios(self): 488 if self._io_refs > 0: 489 self._io_refs -= 1 490 if self._closed: 491 self.close() 492 493 def _real_close(self, _ss=_socket.socket): 494 # This function should not reference any globals. See issue #808164. 495 _ss.close(self) 496 497 def close(self): 498 # This function should not reference any globals. See issue #808164. 499 self._closed = True 500 if self._io_refs <= 0: 501 self._real_close() 502 503 def detach(self): 504 """detach() -> file descriptor 505 506 Close the socket object without closing the underlying file descriptor. 507 The object cannot be used after this call, but the file descriptor 508 can be reused for other purposes. The file descriptor is returned. 509 """ 510 self._closed = True 511 return super().detach() 512 513 @property 514 def family(self): 515 """Read-only access to the address family for this socket. 516 """ 517 return _intenum_converter(super().family, AddressFamily) 518 519 @property 520 def type(self): 521 """Read-only access to the socket type. 522 """ 523 return _intenum_converter(super().type, SocketKind) 524 525 if os.name == 'nt': 526 def get_inheritable(self): 527 return os.get_handle_inheritable(self.fileno()) 528 def set_inheritable(self, inheritable): 529 os.set_handle_inheritable(self.fileno(), inheritable) 530 else: 531 def get_inheritable(self): 532 return os.get_inheritable(self.fileno()) 533 def set_inheritable(self, inheritable): 534 os.set_inheritable(self.fileno(), inheritable) 535 get_inheritable.__doc__ = "Get the inheritable flag of the socket" 536 set_inheritable.__doc__ = "Set the inheritable flag of the socket" 537 538def fromfd(fd, family, type, proto=0): 539 """ fromfd(fd, family, type[, proto]) -> socket object 540 541 Create a socket object from a duplicate of the given file 542 descriptor. The remaining arguments are the same as for socket(). 543 """ 544 nfd = dup(fd) 545 return socket(family, type, proto, nfd) 546 547if hasattr(_socket.socket, "sendmsg"): 548 import array 549 550 def send_fds(sock, buffers, fds, flags=0, address=None): 551 """ send_fds(sock, buffers, fds[, flags[, address]]) -> integer 552 553 Send the list of file descriptors fds over an AF_UNIX socket. 554 """ 555 return sock.sendmsg(buffers, [(_socket.SOL_SOCKET, 556 _socket.SCM_RIGHTS, array.array("i", fds))]) 557 __all__.append("send_fds") 558 559if hasattr(_socket.socket, "recvmsg"): 560 import array 561 562 def recv_fds(sock, bufsize, maxfds, flags=0): 563 """ recv_fds(sock, bufsize, maxfds[, flags]) -> (data, list of file 564 descriptors, msg_flags, address) 565 566 Receive up to maxfds file descriptors returning the message 567 data and a list containing the descriptors. 568 """ 569 # Array of ints 570 fds = array.array("i") 571 msg, ancdata, flags, addr = sock.recvmsg(bufsize, 572 _socket.CMSG_LEN(maxfds * fds.itemsize)) 573 for cmsg_level, cmsg_type, cmsg_data in ancdata: 574 if (cmsg_level == _socket.SOL_SOCKET and cmsg_type == _socket.SCM_RIGHTS): 575 fds.frombytes(cmsg_data[: 576 len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) 577 578 return msg, list(fds), flags, addr 579 __all__.append("recv_fds") 580 581if hasattr(_socket.socket, "share"): 582 def fromshare(info): 583 """ fromshare(info) -> socket object 584 585 Create a socket object from the bytes object returned by 586 socket.share(pid). 587 """ 588 return socket(0, 0, 0, info) 589 __all__.append("fromshare") 590 591if hasattr(_socket, "socketpair"): 592 593 def socketpair(family=None, type=SOCK_STREAM, proto=0): 594 """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 595 596 Create a pair of socket objects from the sockets returned by the platform 597 socketpair() function. 598 The arguments are the same as for socket() except the default family is 599 AF_UNIX if defined on the platform; otherwise, the default is AF_INET. 600 """ 601 if family is None: 602 try: 603 family = AF_UNIX 604 except NameError: 605 family = AF_INET 606 a, b = _socket.socketpair(family, type, proto) 607 a = socket(family, type, proto, a.detach()) 608 b = socket(family, type, proto, b.detach()) 609 return a, b 610 611else: 612 613 # Origin: https://gist.github.com/4325783, by Geert Jansen. Public domain. 614 def socketpair(family=AF_INET, type=SOCK_STREAM, proto=0): 615 if family == AF_INET: 616 host = _LOCALHOST 617 elif family == AF_INET6: 618 host = _LOCALHOST_V6 619 else: 620 raise ValueError("Only AF_INET and AF_INET6 socket address families " 621 "are supported") 622 if type != SOCK_STREAM: 623 raise ValueError("Only SOCK_STREAM socket type is supported") 624 if proto != 0: 625 raise ValueError("Only protocol zero is supported") 626 627 # We create a connected TCP socket. Note the trick with 628 # setblocking(False) that prevents us from having to create a thread. 629 lsock = socket(family, type, proto) 630 try: 631 lsock.bind((host, 0)) 632 lsock.listen() 633 # On IPv6, ignore flow_info and scope_id 634 addr, port = lsock.getsockname()[:2] 635 csock = socket(family, type, proto) 636 try: 637 csock.setblocking(False) 638 try: 639 csock.connect((addr, port)) 640 except (BlockingIOError, InterruptedError): 641 pass 642 csock.setblocking(True) 643 ssock, _ = lsock.accept() 644 except: 645 csock.close() 646 raise 647 finally: 648 lsock.close() 649 return (ssock, csock) 650 __all__.append("socketpair") 651 652socketpair.__doc__ = """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 653Create a pair of socket objects from the sockets returned by the platform 654socketpair() function. 655The arguments are the same as for socket() except the default family is AF_UNIX 656if defined on the platform; otherwise, the default is AF_INET. 657""" 658 659_blocking_errnos = { EAGAIN, EWOULDBLOCK } 660 661class SocketIO(io.RawIOBase): 662 663 """Raw I/O implementation for stream sockets. 664 665 This class supports the makefile() method on sockets. It provides 666 the raw I/O interface on top of a socket object. 667 """ 668 669 # One might wonder why not let FileIO do the job instead. There are two 670 # main reasons why FileIO is not adapted: 671 # - it wouldn't work under Windows (where you can't used read() and 672 # write() on a socket handle) 673 # - it wouldn't work with socket timeouts (FileIO would ignore the 674 # timeout and consider the socket non-blocking) 675 676 # XXX More docs 677 678 def __init__(self, sock, mode): 679 if mode not in ("r", "w", "rw", "rb", "wb", "rwb"): 680 raise ValueError("invalid mode: %r" % mode) 681 io.RawIOBase.__init__(self) 682 self._sock = sock 683 if "b" not in mode: 684 mode += "b" 685 self._mode = mode 686 self._reading = "r" in mode 687 self._writing = "w" in mode 688 self._timeout_occurred = False 689 690 def readinto(self, b): 691 """Read up to len(b) bytes into the writable buffer *b* and return 692 the number of bytes read. If the socket is non-blocking and no bytes 693 are available, None is returned. 694 695 If *b* is non-empty, a 0 return value indicates that the connection 696 was shutdown at the other end. 697 """ 698 self._checkClosed() 699 self._checkReadable() 700 if self._timeout_occurred: 701 raise OSError("cannot read from timed out object") 702 while True: 703 try: 704 return self._sock.recv_into(b) 705 except timeout: 706 self._timeout_occurred = True 707 raise 708 except error as e: 709 if e.args[0] in _blocking_errnos: 710 return None 711 raise 712 713 def write(self, b): 714 """Write the given bytes or bytearray object *b* to the socket 715 and return the number of bytes written. This can be less than 716 len(b) if not all data could be written. If the socket is 717 non-blocking and no bytes could be written None is returned. 718 """ 719 self._checkClosed() 720 self._checkWritable() 721 try: 722 return self._sock.send(b) 723 except error as e: 724 # XXX what about EINTR? 725 if e.args[0] in _blocking_errnos: 726 return None 727 raise 728 729 def readable(self): 730 """True if the SocketIO is open for reading. 731 """ 732 if self.closed: 733 raise ValueError("I/O operation on closed socket.") 734 return self._reading 735 736 def writable(self): 737 """True if the SocketIO is open for writing. 738 """ 739 if self.closed: 740 raise ValueError("I/O operation on closed socket.") 741 return self._writing 742 743 def seekable(self): 744 """True if the SocketIO is open for seeking. 745 """ 746 if self.closed: 747 raise ValueError("I/O operation on closed socket.") 748 return super().seekable() 749 750 def fileno(self): 751 """Return the file descriptor of the underlying socket. 752 """ 753 self._checkClosed() 754 return self._sock.fileno() 755 756 @property 757 def name(self): 758 if not self.closed: 759 return self.fileno() 760 else: 761 return -1 762 763 @property 764 def mode(self): 765 return self._mode 766 767 def close(self): 768 """Close the SocketIO object. This doesn't close the underlying 769 socket, except if all references to it have disappeared. 770 """ 771 if self.closed: 772 return 773 io.RawIOBase.close(self) 774 self._sock._decref_socketios() 775 self._sock = None 776 777 778def getfqdn(name=''): 779 """Get fully qualified domain name from name. 780 781 An empty argument is interpreted as meaning the local host. 782 783 First the hostname returned by gethostbyaddr() is checked, then 784 possibly existing aliases. In case no FQDN is available, hostname 785 from gethostname() is returned. 786 """ 787 name = name.strip() 788 if not name or name == '0.0.0.0': 789 name = gethostname() 790 try: 791 hostname, aliases, ipaddrs = gethostbyaddr(name) 792 except error: 793 pass 794 else: 795 aliases.insert(0, hostname) 796 for name in aliases: 797 if '.' in name: 798 break 799 else: 800 name = hostname 801 return name 802 803 804_GLOBAL_DEFAULT_TIMEOUT = object() 805 806def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT, 807 source_address=None): 808 """Connect to *address* and return the socket object. 809 810 Convenience function. Connect to *address* (a 2-tuple ``(host, 811 port)``) and return the socket object. Passing the optional 812 *timeout* parameter will set the timeout on the socket instance 813 before attempting to connect. If no *timeout* is supplied, the 814 global default timeout setting returned by :func:`getdefaulttimeout` 815 is used. If *source_address* is set it must be a tuple of (host, port) 816 for the socket to bind as a source address before making the connection. 817 A host of '' or port 0 tells the OS to use the default. 818 """ 819 820 host, port = address 821 err = None 822 for res in getaddrinfo(host, port, 0, SOCK_STREAM): 823 af, socktype, proto, canonname, sa = res 824 sock = None 825 try: 826 sock = socket(af, socktype, proto) 827 if timeout is not _GLOBAL_DEFAULT_TIMEOUT: 828 sock.settimeout(timeout) 829 if source_address: 830 sock.bind(source_address) 831 sock.connect(sa) 832 # Break explicitly a reference cycle 833 err = None 834 return sock 835 836 except error as _: 837 err = _ 838 if sock is not None: 839 sock.close() 840 841 if err is not None: 842 try: 843 raise err 844 finally: 845 # Break explicitly a reference cycle 846 err = None 847 else: 848 raise error("getaddrinfo returns an empty list") 849 850 851def has_dualstack_ipv6(): 852 """Return True if the platform supports creating a SOCK_STREAM socket 853 which can handle both AF_INET and AF_INET6 (IPv4 / IPv6) connections. 854 """ 855 if not has_ipv6 \ 856 or not hasattr(_socket, 'IPPROTO_IPV6') \ 857 or not hasattr(_socket, 'IPV6_V6ONLY'): 858 return False 859 try: 860 with socket(AF_INET6, SOCK_STREAM) as sock: 861 sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 0) 862 return True 863 except error: 864 return False 865 866 867def create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, 868 dualstack_ipv6=False): 869 """Convenience function which creates a SOCK_STREAM type socket 870 bound to *address* (a 2-tuple (host, port)) and return the socket 871 object. 872 873 *family* should be either AF_INET or AF_INET6. 874 *backlog* is the queue size passed to socket.listen(). 875 *reuse_port* dictates whether to use the SO_REUSEPORT socket option. 876 *dualstack_ipv6*: if true and the platform supports it, it will 877 create an AF_INET6 socket able to accept both IPv4 or IPv6 878 connections. When false it will explicitly disable this option on 879 platforms that enable it by default (e.g. Linux). 880 881 >>> with create_server(('', 8000)) as server: 882 ... while True: 883 ... conn, addr = server.accept() 884 ... # handle new connection 885 """ 886 if reuse_port and not hasattr(_socket, "SO_REUSEPORT"): 887 raise ValueError("SO_REUSEPORT not supported on this platform") 888 if dualstack_ipv6: 889 if not has_dualstack_ipv6(): 890 raise ValueError("dualstack_ipv6 not supported on this platform") 891 if family != AF_INET6: 892 raise ValueError("dualstack_ipv6 requires AF_INET6 family") 893 sock = socket(family, SOCK_STREAM) 894 try: 895 # Note about Windows. We don't set SO_REUSEADDR because: 896 # 1) It's unnecessary: bind() will succeed even in case of a 897 # previous closed socket on the same address and still in 898 # TIME_WAIT state. 899 # 2) If set, another socket is free to bind() on the same 900 # address, effectively preventing this one from accepting 901 # connections. Also, it may set the process in a state where 902 # it'll no longer respond to any signals or graceful kills. 903 # See: msdn2.microsoft.com/en-us/library/ms740621(VS.85).aspx 904 if os.name not in ('nt', 'cygwin') and \ 905 hasattr(_socket, 'SO_REUSEADDR'): 906 try: 907 sock.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1) 908 except error: 909 # Fail later on bind(), for platforms which may not 910 # support this option. 911 pass 912 if reuse_port: 913 sock.setsockopt(SOL_SOCKET, SO_REUSEPORT, 1) 914 if has_ipv6 and family == AF_INET6: 915 if dualstack_ipv6: 916 sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 0) 917 elif hasattr(_socket, "IPV6_V6ONLY") and \ 918 hasattr(_socket, "IPPROTO_IPV6"): 919 sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 1) 920 try: 921 sock.bind(address) 922 except error as err: 923 msg = '%s (while attempting to bind on address %r)' % \ 924 (err.strerror, address) 925 raise error(err.errno, msg) from None 926 if backlog is None: 927 sock.listen() 928 else: 929 sock.listen(backlog) 930 return sock 931 except error: 932 sock.close() 933 raise 934 935 936def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0): 937 """Resolve host and port into list of address info entries. 938 939 Translate the host/port argument into a sequence of 5-tuples that contain 940 all the necessary arguments for creating a socket connected to that service. 941 host is a domain name, a string representation of an IPv4/v6 address or 942 None. port is a string service name such as 'http', a numeric port number or 943 None. By passing None as the value of host and port, you can pass NULL to 944 the underlying C API. 945 946 The family, type and proto arguments can be optionally specified in order to 947 narrow the list of addresses returned. Passing zero as a value for each of 948 these arguments selects the full range of results. 949 """ 950 # We override this function since we want to translate the numeric family 951 # and socket type values to enum constants. 952 addrlist = [] 953 for res in _socket.getaddrinfo(host, port, family, type, proto, flags): 954 af, socktype, proto, canonname, sa = res 955 addrlist.append((_intenum_converter(af, AddressFamily), 956 _intenum_converter(socktype, SocketKind), 957 proto, canonname, sa)) 958 return addrlist 959