1 # Wrapper module for _socket, providing some additional facilities 2 # implemented in Python. 3 4 """\ 5 This module provides socket operations and some related functions. 6 On Unix, it supports IP (Internet Protocol) and Unix domain sockets. 7 On other systems, it only supports IP. Functions specific for a 8 socket are available as methods of the socket object. 9 10 Functions: 11 12 socket() -- create a new socket object 13 socketpair() -- create a pair of new socket objects [*] 14 fromfd() -- create a socket object from an open file descriptor [*] 15 fromshare() -- create a socket object from data received from socket.share() [*] 16 gethostname() -- return the current hostname 17 gethostbyname() -- map a hostname to its IP number 18 gethostbyaddr() -- map an IP number or hostname to DNS info 19 getservbyname() -- map a service name and a protocol name to a port number 20 getprotobyname() -- map a protocol name (e.g. 'tcp') to a number 21 ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order 22 htons(), htonl() -- convert 16, 32 bit int from host to network byte order 23 inet_aton() -- convert IP addr string (123.45.67.89) to 32-bit packed format 24 inet_ntoa() -- convert 32-bit packed format IP to string (123.45.67.89) 25 socket.getdefaulttimeout() -- get the default timeout value 26 socket.setdefaulttimeout() -- set the default timeout value 27 create_connection() -- connects to an address, with an optional timeout and 28 optional source address. 29 30 [*] not available on all platforms! 31 32 Special objects: 33 34 SocketType -- type object for socket objects 35 error -- exception raised for I/O errors 36 has_ipv6 -- boolean value indicating if IPv6 is supported 37 38 IntEnum constants: 39 40 AF_INET, AF_UNIX -- socket domains (first argument to socket() call) 41 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument) 42 43 Integer constants: 44 45 Many other constants may be defined; these may be used in calls to 46 the setsockopt() and getsockopt() methods. 47 """ 48 49 import _socket 50 from _socket import * 51 52 import os, sys, io, selectors 53 from enum import IntEnum, IntFlag 54 55 try: 56 import errno 57 except ImportError: 58 errno = None 59 EBADF = getattr(errno, 'EBADF', 9) 60 EAGAIN = getattr(errno, 'EAGAIN', 11) 61 EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11) 62 63 __all__ = ["fromfd", "getfqdn", "create_connection", 64 "AddressFamily", "SocketKind"] 65 __all__.extend(os._get_exports_list(_socket)) 66 67 # Set up the socket.AF_* socket.SOCK_* constants as members of IntEnums for 68 # nicer string representations. 69 # Note that _socket only knows about the integer values. The public interface 70 # in this module understands the enums and translates them back from integers 71 # where needed (e.g. .family property of a socket object). 72 73 IntEnum._convert( 74 'AddressFamily', 75 __name__, 76 lambda C: C.isupper() and C.startswith('AF_')) 77 78 IntEnum._convert( 79 'SocketKind', 80 __name__, 81 lambda C: C.isupper() and C.startswith('SOCK_')) 82 83 IntFlag._convert( 84 'MsgFlag', 85 __name__, 86 lambda C: C.isupper() and C.startswith('MSG_')) 87 88 IntFlag._convert( 89 'AddressInfo', 90 __name__, 91 lambda C: C.isupper() and C.startswith('AI_')) 92 93 _LOCALHOST = '127.0.0.1' 94 _LOCALHOST_V6 = '::1' 95 96 97 def _intenum_converter(value, enum_klass): 98 """Convert a numeric family value to an IntEnum member. 99 100 If it's not a known member, return the numeric value itself. 101 """ 102 try: 103 return enum_klass(value) 104 except ValueError: 105 return value 106 107 _realsocket = socket 108 109 # WSA error codes 110 if sys.platform.lower().startswith("win"): 111 errorTab = {} 112 errorTab[10004] = "The operation was interrupted." 113 errorTab[10009] = "A bad file handle was passed." 114 errorTab[10013] = "Permission denied." 115 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT 116 errorTab[10022] = "An invalid operation was attempted." 117 errorTab[10035] = "The socket operation would block" 118 errorTab[10036] = "A blocking operation is already in progress." 119 errorTab[10048] = "The network address is in use." 120 errorTab[10054] = "The connection has been reset." 121 errorTab[10058] = "The network has been shut down." 122 errorTab[10060] = "The operation timed out." 123 errorTab[10061] = "Connection refused." 124 errorTab[10063] = "The name is too long." 125 errorTab[10064] = "The host is down." 126 errorTab[10065] = "The host is unreachable." 127 __all__.append("errorTab") 128 129 130 class _GiveupOnSendfile(Exception): pass 131 132 133 class socket(_socket.socket): 134 135 """A subclass of _socket.socket adding the makefile() method.""" 136 137 __slots__ = ["__weakref__", "_io_refs", "_closed"] 138 139 def __init__(self, family=-1, type=-1, proto=-1, fileno=None): 140 # For user code address family and type values are IntEnum members, but 141 # for the underlying _socket.socket they're just integers. The 142 # constructor of _socket.socket converts the given argument to an 143 # integer automatically. 144 if fileno is None: 145 if family == -1: 146 family = AF_INET 147 if type == -1: 148 type = SOCK_STREAM 149 if proto == -1: 150 proto = 0 151 _socket.socket.__init__(self, family, type, proto, fileno) 152 self._io_refs = 0 153 self._closed = False 154 155 def __enter__(self): 156 return self 157 158 def __exit__(self, *args): 159 if not self._closed: 160 self.close() 161 162 def __repr__(self): 163 """Wrap __repr__() to reveal the real class name and socket 164 address(es). 165 """ 166 closed = getattr(self, '_closed', False) 167 s = "<%s.%s%s fd=%i, family=%s, type=%s, proto=%i" \ 168 % (self.__class__.__module__, 169 self.__class__.__qualname__, 170 " [closed]" if closed else "", 171 self.fileno(), 172 self.family, 173 self.type, 174 self.proto) 175 if not closed: 176 try: 177 laddr = self.getsockname() 178 if laddr: 179 s += ", laddr=%s" % str(laddr) 180 except error: 181 pass 182 try: 183 raddr = self.getpeername() 184 if raddr: 185 s += ", raddr=%s" % str(raddr) 186 except error: 187 pass 188 s += '>' 189 return s 190 191 def __getstate__(self): 192 raise TypeError("Cannot serialize socket object") 193 194 def dup(self): 195 """dup() -> socket object 196 197 Duplicate the socket. Return a new socket object connected to the same 198 system resource. The new socket is non-inheritable. 199 """ 200 fd = dup(self.fileno()) 201 sock = self.__class__(self.family, self.type, self.proto, fileno=fd) 202 sock.settimeout(self.gettimeout()) 203 return sock 204 205 def accept(self): 206 """accept() -> (socket object, address info) 207 208 Wait for an incoming connection. Return a new socket 209 representing the connection, and the address of the client. 210 For IP sockets, the address info is a pair (hostaddr, port). 211 """ 212 fd, addr = self._accept() 213 sock = socket(self.family, self.type, self.proto, fileno=fd) 214 # Issue #7995: if no default timeout is set and the listening 215 # socket had a (non-zero) timeout, force the new socket in blocking 216 # mode to override platform-specific socket flags inheritance. 217 if getdefaulttimeout() is None and self.gettimeout(): 218 sock.setblocking(True) 219 return sock, addr 220 221 def makefile(self, mode="r", buffering=None, *, 222 encoding=None, errors=None, newline=None): 223 """makefile(...) -> an I/O stream connected to the socket 224 225 The arguments are as for io.open() after the filename, except the only 226 supported mode values are 'r' (default), 'w' and 'b'. 227 """ 228 # XXX refactor to share code? 229 if not set(mode) <= {"r", "w", "b"}: 230 raise ValueError("invalid mode %r (only r, w, b allowed)" % (mode,)) 231 writing = "w" in mode 232 reading = "r" in mode or not writing 233 assert reading or writing 234 binary = "b" in mode 235 rawmode = "" 236 if reading: 237 rawmode += "r" 238 if writing: 239 rawmode += "w" 240 raw = SocketIO(self, rawmode) 241 self._io_refs += 1 242 if buffering is None: 243 buffering = -1 244 if buffering < 0: 245 buffering = io.DEFAULT_BUFFER_SIZE 246 if buffering == 0: 247 if not binary: 248 raise ValueError("unbuffered streams must be binary") 249 return raw 250 if reading and writing: 251 buffer = io.BufferedRWPair(raw, raw, buffering) 252 elif reading: 253 buffer = io.BufferedReader(raw, buffering) 254 else: 255 assert writing 256 buffer = io.BufferedWriter(raw, buffering) 257 if binary: 258 return buffer 259 text = io.TextIOWrapper(buffer, encoding, errors, newline) 260 text.mode = mode 261 return text 262 263 if hasattr(os, 'sendfile'): 264 265 def _sendfile_use_sendfile(self, file, offset=0, count=None): 266 self._check_sendfile_params(file, offset, count) 267 sockno = self.fileno() 268 try: 269 fileno = file.fileno() 270 except (AttributeError, io.UnsupportedOperation) as err: 271 raise _GiveupOnSendfile(err) # not a regular file 272 try: 273 fsize = os.fstat(fileno).st_size 274 except OSError as err: 275 raise _GiveupOnSendfile(err) # not a regular file 276 if not fsize: 277 return 0 # empty file 278 blocksize = fsize if not count else count 279 280 timeout = self.gettimeout() 281 if timeout == 0: 282 raise ValueError("non-blocking sockets are not supported") 283 # poll/select have the advantage of not requiring any 284 # extra file descriptor, contrarily to epoll/kqueue 285 # (also, they require a single syscall). 286 if hasattr(selectors, 'PollSelector'): 287 selector = selectors.PollSelector() 288 else: 289 selector = selectors.SelectSelector() 290 selector.register(sockno, selectors.EVENT_WRITE) 291 292 total_sent = 0 293 # localize variable access to minimize overhead 294 selector_select = selector.select 295 os_sendfile = os.sendfile 296 try: 297 while True: 298 if timeout and not selector_select(timeout): 299 raise _socket.timeout('timed out') 300 if count: 301 blocksize = count - total_sent 302 if blocksize <= 0: 303 break 304 try: 305 sent = os_sendfile(sockno, fileno, offset, blocksize) 306 except BlockingIOError: 307 if not timeout: 308 # Block until the socket is ready to send some 309 # data; avoids hogging CPU resources. 310 selector_select() 311 continue 312 except OSError as err: 313 if total_sent == 0: 314 # We can get here for different reasons, the main 315 # one being 'file' is not a regular mmap(2)-like 316 # file, in which case we'll fall back on using 317 # plain send(). 318 raise _GiveupOnSendfile(err) 319 raise err from None 320 else: 321 if sent == 0: 322 break # EOF 323 offset += sent 324 total_sent += sent 325 return total_sent 326 finally: 327 if total_sent > 0 and hasattr(file, 'seek'): 328 file.seek(offset) 329 else: 330 def _sendfile_use_sendfile(self, file, offset=0, count=None): 331 raise _GiveupOnSendfile( 332 "os.sendfile() not available on this platform") 333 334 def _sendfile_use_send(self, file, offset=0, count=None): 335 self._check_sendfile_params(file, offset, count) 336 if self.gettimeout() == 0: 337 raise ValueError("non-blocking sockets are not supported") 338 if offset: 339 file.seek(offset) 340 blocksize = min(count, 8192) if count else 8192 341 total_sent = 0 342 # localize variable access to minimize overhead 343 file_read = file.read 344 sock_send = self.send 345 try: 346 while True: 347 if count: 348 blocksize = min(count - total_sent, blocksize) 349 if blocksize <= 0: 350 break 351 data = memoryview(file_read(blocksize)) 352 if not data: 353 break # EOF 354 while True: 355 try: 356 sent = sock_send(data) 357 except BlockingIOError: 358 continue 359 else: 360 total_sent += sent 361 if sent < len(data): 362 data = data[sent:] 363 else: 364 break 365 return total_sent 366 finally: 367 if total_sent > 0 and hasattr(file, 'seek'): 368 file.seek(offset + total_sent) 369 370 def _check_sendfile_params(self, file, offset, count): 371 if 'b' not in getattr(file, 'mode', 'b'): 372 raise ValueError("file should be opened in binary mode") 373 if not self.type & SOCK_STREAM: 374 raise ValueError("only SOCK_STREAM type sockets are supported") 375 if count is not None: 376 if not isinstance(count, int): 377 raise TypeError( 378 "count must be a positive integer (got {!r})".format(count)) 379 if count <= 0: 380 raise ValueError( 381 "count must be a positive integer (got {!r})".format(count)) 382 383 def sendfile(self, file, offset=0, count=None): 384 """sendfile(file[, offset[, count]]) -> sent 385 386 Send a file until EOF is reached by using high-performance 387 os.sendfile() and return the total number of bytes which 388 were sent. 389 *file* must be a regular file object opened in binary mode. 390 If os.sendfile() is not available (e.g. Windows) or file is 391 not a regular file socket.send() will be used instead. 392 *offset* tells from where to start reading the file. 393 If specified, *count* is the total number of bytes to transmit 394 as opposed to sending the file until EOF is reached. 395 File position is updated on return or also in case of error in 396 which case file.tell() can be used to figure out the number of 397 bytes which were sent. 398 The socket must be of SOCK_STREAM type. 399 Non-blocking sockets are not supported. 400 """ 401 try: 402 return self._sendfile_use_sendfile(file, offset, count) 403 except _GiveupOnSendfile: 404 return self._sendfile_use_send(file, offset, count) 405 406 def _decref_socketios(self): 407 if self._io_refs > 0: 408 self._io_refs -= 1 409 if self._closed: 410 self.close() 411 412 def _real_close(self, _ss=_socket.socket): 413 # This function should not reference any globals. See issue #808164. 414 _ss.close(self) 415 416 def close(self): 417 # This function should not reference any globals. See issue #808164. 418 self._closed = True 419 if self._io_refs <= 0: 420 self._real_close() 421 422 def detach(self): 423 """detach() -> file descriptor 424 425 Close the socket object without closing the underlying file descriptor. 426 The object cannot be used after this call, but the file descriptor 427 can be reused for other purposes. The file descriptor is returned. 428 """ 429 self._closed = True 430 return super().detach() 431 432 @property 433 def family(self): 434 """Read-only access to the address family for this socket. 435 """ 436 return _intenum_converter(super().family, AddressFamily) 437 438 @property 439 def type(self): 440 """Read-only access to the socket type. 441 """ 442 return _intenum_converter(super().type, SocketKind) 443 444 if os.name == 'nt': 445 def get_inheritable(self): 446 return os.get_handle_inheritable(self.fileno()) 447 def set_inheritable(self, inheritable): 448 os.set_handle_inheritable(self.fileno(), inheritable) 449 else: 450 def get_inheritable(self): 451 return os.get_inheritable(self.fileno()) 452 def set_inheritable(self, inheritable): 453 os.set_inheritable(self.fileno(), inheritable) 454 get_inheritable.__doc__ = "Get the inheritable flag of the socket" 455 set_inheritable.__doc__ = "Set the inheritable flag of the socket" 456 457 def fromfd(fd, family, type, proto=0): 458 """ fromfd(fd, family, type[, proto]) -> socket object 459 460 Create a socket object from a duplicate of the given file 461 descriptor. The remaining arguments are the same as for socket(). 462 """ 463 nfd = dup(fd) 464 return socket(family, type, proto, nfd) 465 466 if hasattr(_socket.socket, "share"): 467 def fromshare(info): 468 """ fromshare(info) -> socket object 469 470 Create a socket object from the bytes object returned by 471 socket.share(pid). 472 """ 473 return socket(0, 0, 0, info) 474 __all__.append("fromshare") 475 476 if hasattr(_socket, "socketpair"): 477 478 def socketpair(family=None, type=SOCK_STREAM, proto=0): 479 """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 480 481 Create a pair of socket objects from the sockets returned by the platform 482 socketpair() function. 483 The arguments are the same as for socket() except the default family is 484 AF_UNIX if defined on the platform; otherwise, the default is AF_INET. 485 """ 486 if family is None: 487 try: 488 family = AF_UNIX 489 except NameError: 490 family = AF_INET 491 a, b = _socket.socketpair(family, type, proto) 492 a = socket(family, type, proto, a.detach()) 493 b = socket(family, type, proto, b.detach()) 494 return a, b 495 496 else: 497 498 # Origin: https://gist.github.com/4325783, by Geert Jansen. Public domain. 499 def socketpair(family=AF_INET, type=SOCK_STREAM, proto=0): 500 if family == AF_INET: 501 host = _LOCALHOST 502 elif family == AF_INET6: 503 host = _LOCALHOST_V6 504 else: 505 raise ValueError("Only AF_INET and AF_INET6 socket address families " 506 "are supported") 507 if type != SOCK_STREAM: 508 raise ValueError("Only SOCK_STREAM socket type is supported") 509 if proto != 0: 510 raise ValueError("Only protocol zero is supported") 511 512 # We create a connected TCP socket. Note the trick with 513 # setblocking(False) that prevents us from having to create a thread. 514 lsock = socket(family, type, proto) 515 try: 516 lsock.bind((host, 0)) 517 lsock.listen() 518 # On IPv6, ignore flow_info and scope_id 519 addr, port = lsock.getsockname()[:2] 520 csock = socket(family, type, proto) 521 try: 522 csock.setblocking(False) 523 try: 524 csock.connect((addr, port)) 525 except (BlockingIOError, InterruptedError): 526 pass 527 csock.setblocking(True) 528 ssock, _ = lsock.accept() 529 except: 530 csock.close() 531 raise 532 finally: 533 lsock.close() 534 return (ssock, csock) 535 __all__.append("socketpair") 536 537 socketpair.__doc__ = """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 538 Create a pair of socket objects from the sockets returned by the platform 539 socketpair() function. 540 The arguments are the same as for socket() except the default family is AF_UNIX 541 if defined on the platform; otherwise, the default is AF_INET. 542 """ 543 544 _blocking_errnos = { EAGAIN, EWOULDBLOCK } 545 546 class SocketIO(io.RawIOBase): 547 548 """Raw I/O implementation for stream sockets. 549 550 This class supports the makefile() method on sockets. It provides 551 the raw I/O interface on top of a socket object. 552 """ 553 554 # One might wonder why not let FileIO do the job instead. There are two 555 # main reasons why FileIO is not adapted: 556 # - it wouldn't work under Windows (where you can't used read() and 557 # write() on a socket handle) 558 # - it wouldn't work with socket timeouts (FileIO would ignore the 559 # timeout and consider the socket non-blocking) 560 561 # XXX More docs 562 563 def __init__(self, sock, mode): 564 if mode not in ("r", "w", "rw", "rb", "wb", "rwb"): 565 raise ValueError("invalid mode: %r" % mode) 566 io.RawIOBase.__init__(self) 567 self._sock = sock 568 if "b" not in mode: 569 mode += "b" 570 self._mode = mode 571 self._reading = "r" in mode 572 self._writing = "w" in mode 573 self._timeout_occurred = False 574 575 def readinto(self, b): 576 """Read up to len(b) bytes into the writable buffer *b* and return 577 the number of bytes read. If the socket is non-blocking and no bytes 578 are available, None is returned. 579 580 If *b* is non-empty, a 0 return value indicates that the connection 581 was shutdown at the other end. 582 """ 583 self._checkClosed() 584 self._checkReadable() 585 if self._timeout_occurred: 586 raise OSError("cannot read from timed out object") 587 while True: 588 try: 589 return self._sock.recv_into(b) 590 except timeout: 591 self._timeout_occurred = True 592 raise 593 except error as e: 594 if e.args[0] in _blocking_errnos: 595 return None 596 raise 597 598 def write(self, b): 599 """Write the given bytes or bytearray object *b* to the socket 600 and return the number of bytes written. This can be less than 601 len(b) if not all data could be written. If the socket is 602 non-blocking and no bytes could be written None is returned. 603 """ 604 self._checkClosed() 605 self._checkWritable() 606 try: 607 return self._sock.send(b) 608 except error as e: 609 # XXX what about EINTR? 610 if e.args[0] in _blocking_errnos: 611 return None 612 raise 613 614 def readable(self): 615 """True if the SocketIO is open for reading. 616 """ 617 if self.closed: 618 raise ValueError("I/O operation on closed socket.") 619 return self._reading 620 621 def writable(self): 622 """True if the SocketIO is open for writing. 623 """ 624 if self.closed: 625 raise ValueError("I/O operation on closed socket.") 626 return self._writing 627 628 def seekable(self): 629 """True if the SocketIO is open for seeking. 630 """ 631 if self.closed: 632 raise ValueError("I/O operation on closed socket.") 633 return super().seekable() 634 635 def fileno(self): 636 """Return the file descriptor of the underlying socket. 637 """ 638 self._checkClosed() 639 return self._sock.fileno() 640 641 @property 642 def name(self): 643 if not self.closed: 644 return self.fileno() 645 else: 646 return -1 647 648 @property 649 def mode(self): 650 return self._mode 651 652 def close(self): 653 """Close the SocketIO object. This doesn't close the underlying 654 socket, except if all references to it have disappeared. 655 """ 656 if self.closed: 657 return 658 io.RawIOBase.close(self) 659 self._sock._decref_socketios() 660 self._sock = None 661 662 663 def getfqdn(name=''): 664 """Get fully qualified domain name from name. 665 666 An empty argument is interpreted as meaning the local host. 667 668 First the hostname returned by gethostbyaddr() is checked, then 669 possibly existing aliases. In case no FQDN is available, hostname 670 from gethostname() is returned. 671 """ 672 name = name.strip() 673 if not name or name == '0.0.0.0': 674 name = gethostname() 675 try: 676 hostname, aliases, ipaddrs = gethostbyaddr(name) 677 except error: 678 pass 679 else: 680 aliases.insert(0, hostname) 681 for name in aliases: 682 if '.' in name: 683 break 684 else: 685 name = hostname 686 return name 687 688 689 _GLOBAL_DEFAULT_TIMEOUT = object() 690 691 def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT, 692 source_address=None): 693 """Connect to *address* and return the socket object. 694 695 Convenience function. Connect to *address* (a 2-tuple ``(host, 696 port)``) and return the socket object. Passing the optional 697 *timeout* parameter will set the timeout on the socket instance 698 before attempting to connect. If no *timeout* is supplied, the 699 global default timeout setting returned by :func:`getdefaulttimeout` 700 is used. If *source_address* is set it must be a tuple of (host, port) 701 for the socket to bind as a source address before making the connection. 702 A host of '' or port 0 tells the OS to use the default. 703 """ 704 705 host, port = address 706 err = None 707 for res in getaddrinfo(host, port, 0, SOCK_STREAM): 708 af, socktype, proto, canonname, sa = res 709 sock = None 710 try: 711 sock = socket(af, socktype, proto) 712 if timeout is not _GLOBAL_DEFAULT_TIMEOUT: 713 sock.settimeout(timeout) 714 if source_address: 715 sock.bind(source_address) 716 sock.connect(sa) 717 # Break explicitly a reference cycle 718 err = None 719 return sock 720 721 except error as _: 722 err = _ 723 if sock is not None: 724 sock.close() 725 726 if err is not None: 727 raise err 728 else: 729 raise error("getaddrinfo returns an empty list") 730 731 def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0): 732 """Resolve host and port into list of address info entries. 733 734 Translate the host/port argument into a sequence of 5-tuples that contain 735 all the necessary arguments for creating a socket connected to that service. 736 host is a domain name, a string representation of an IPv4/v6 address or 737 None. port is a string service name such as 'http', a numeric port number or 738 None. By passing None as the value of host and port, you can pass NULL to 739 the underlying C API. 740 741 The family, type and proto arguments can be optionally specified in order to 742 narrow the list of addresses returned. Passing zero as a value for each of 743 these arguments selects the full range of results. 744 """ 745 # We override this function since we want to translate the numeric family 746 # and socket type values to enum constants. 747 addrlist = [] 748 for res in _socket.getaddrinfo(host, port, family, type, proto, flags): 749 af, socktype, proto, canonname, sa = res 750 addrlist.append((_intenum_converter(af, AddressFamily), 751 _intenum_converter(socktype, SocketKind), 752 proto, canonname, sa)) 753 return addrlist 754
