/Lib/socket.py
Python | 514 lines | 495 code | 2 blank | 17 comment | 1 complexity | 54eb32c64ac61512f0e3f92567ab8241 MD5 | raw file
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 [*] 15gethostname() -- return the current hostname 16gethostbyname() -- map a hostname to its IP number 17gethostbyaddr() -- map an IP number or hostname to DNS info 18getservbyname() -- map a service name and a protocol name to a port number 19getprotobyname() -- map a protocol name (e.g. 'tcp') to a number 20ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order 21htons(), htonl() -- convert 16, 32 bit int from host to network byte order 22inet_aton() -- convert IP addr string (123.45.67.89) to 32-bit packed format 23inet_ntoa() -- convert 32-bit packed format IP to string (123.45.67.89) 24ssl() -- secure socket layer support (only available if configured) 25socket.getdefaulttimeout() -- get the default timeout value 26socket.setdefaulttimeout() -- set the default timeout value 27create_connection() -- connects to an address, with an optional timeout 28 29 [*] not available on all platforms! 30 31Special objects: 32 33SocketType -- type object for socket objects 34error -- exception raised for I/O errors 35has_ipv6 -- boolean value indicating if IPv6 is supported 36 37Integer constants: 38 39AF_INET, AF_UNIX -- socket domains (first argument to socket() call) 40SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument) 41 42Many other constants may be defined; these may be used in calls to 43the setsockopt() and getsockopt() methods. 44""" 45 46import _socket 47from _socket import * 48 49try: 50 import _ssl 51except ImportError: 52 # no SSL support 53 pass 54else: 55 def ssl(sock, keyfile=None, certfile=None): 56 # we do an internal import here because the ssl 57 # module imports the socket module 58 import ssl as _realssl 59 warnings.warn("socket.ssl() is deprecated. Use ssl.wrap_socket() instead.", 60 DeprecationWarning, stacklevel=2) 61 return _realssl.sslwrap_simple(sock, keyfile, certfile) 62 63 # we need to import the same constants we used to... 64 from _ssl import SSLError as sslerror 65 from _ssl import \ 66 RAND_add, \ 67 RAND_egd, \ 68 RAND_status, \ 69 SSL_ERROR_ZERO_RETURN, \ 70 SSL_ERROR_WANT_READ, \ 71 SSL_ERROR_WANT_WRITE, \ 72 SSL_ERROR_WANT_X509_LOOKUP, \ 73 SSL_ERROR_SYSCALL, \ 74 SSL_ERROR_SSL, \ 75 SSL_ERROR_WANT_CONNECT, \ 76 SSL_ERROR_EOF, \ 77 SSL_ERROR_INVALID_ERROR_CODE 78 79import os, sys, warnings 80 81try: 82 from cStringIO import StringIO 83except ImportError: 84 from StringIO import StringIO 85 86try: 87 from errno import EBADF 88except ImportError: 89 EBADF = 9 90 91__all__ = ["getfqdn", "create_connection"] 92__all__.extend(os._get_exports_list(_socket)) 93 94 95_realsocket = socket 96 97# WSA error codes 98if sys.platform.lower().startswith("win"): 99 errorTab = {} 100 errorTab[10004] = "The operation was interrupted." 101 errorTab[10009] = "A bad file handle was passed." 102 errorTab[10013] = "Permission denied." 103 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT 104 errorTab[10022] = "An invalid operation was attempted." 105 errorTab[10035] = "The socket operation would block" 106 errorTab[10036] = "A blocking operation is already in progress." 107 errorTab[10048] = "The network address is in use." 108 errorTab[10054] = "The connection has been reset." 109 errorTab[10058] = "The network has been shut down." 110 errorTab[10060] = "The operation timed out." 111 errorTab[10061] = "Connection refused." 112 errorTab[10063] = "The name is too long." 113 errorTab[10064] = "The host is down." 114 errorTab[10065] = "The host is unreachable." 115 __all__.append("errorTab") 116 117 118 119def getfqdn(name=''): 120 """Get fully qualified domain name from name. 121 122 An empty argument is interpreted as meaning the local host. 123 124 First the hostname returned by gethostbyaddr() is checked, then 125 possibly existing aliases. In case no FQDN is available, hostname 126 from gethostname() is returned. 127 """ 128 name = name.strip() 129 if not name or name == '0.0.0.0': 130 name = gethostname() 131 try: 132 hostname, aliases, ipaddrs = gethostbyaddr(name) 133 except error: 134 pass 135 else: 136 aliases.insert(0, hostname) 137 for name in aliases: 138 if '.' in name: 139 break 140 else: 141 name = hostname 142 return name 143 144 145_socketmethods = ( 146 'bind', 'connect', 'connect_ex', 'fileno', 'listen', 147 'getpeername', 'getsockname', 'getsockopt', 'setsockopt', 148 'sendall', 'setblocking', 149 'settimeout', 'gettimeout', 'shutdown') 150 151if os.name == "nt": 152 _socketmethods = _socketmethods + ('ioctl',) 153 154if sys.platform == "riscos": 155 _socketmethods = _socketmethods + ('sleeptaskw',) 156 157# All the method names that must be delegated to either the real socket 158# object or the _closedsocket object. 159_delegate_methods = ("recv", "recvfrom", "recv_into", "recvfrom_into", 160 "send", "sendto") 161 162class _closedsocket(object): 163 __slots__ = [] 164 def _dummy(*args): 165 raise error(EBADF, 'Bad file descriptor') 166 # All _delegate_methods must also be initialized here. 167 send = recv = recv_into = sendto = recvfrom = recvfrom_into = _dummy 168 __getattr__ = _dummy 169 170# Wrapper around platform socket objects. This implements 171# a platform-independent dup() functionality. The 172# implementation currently relies on reference counting 173# to close the underlying socket object. 174class _socketobject(object): 175 176 __doc__ = _realsocket.__doc__ 177 178 __slots__ = ["_sock", "__weakref__"] + list(_delegate_methods) 179 180 def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, _sock=None): 181 if _sock is None: 182 _sock = _realsocket(family, type, proto) 183 self._sock = _sock 184 for method in _delegate_methods: 185 setattr(self, method, getattr(_sock, method)) 186 187 def close(self): 188 self._sock = _closedsocket() 189 dummy = self._sock._dummy 190 for method in _delegate_methods: 191 setattr(self, method, dummy) 192 close.__doc__ = _realsocket.close.__doc__ 193 194 def accept(self): 195 sock, addr = self._sock.accept() 196 return _socketobject(_sock=sock), addr 197 accept.__doc__ = _realsocket.accept.__doc__ 198 199 def dup(self): 200 """dup() -> socket object 201 202 Return a new socket object connected to the same system resource.""" 203 return _socketobject(_sock=self._sock) 204 205 def makefile(self, mode='r', bufsize=-1): 206 """makefile([mode[, bufsize]]) -> file object 207 208 Return a regular file object corresponding to the socket. The mode 209 and bufsize arguments are as for the built-in open() function.""" 210 return _fileobject(self._sock, mode, bufsize) 211 212 family = property(lambda self: self._sock.family, doc="the socket family") 213 type = property(lambda self: self._sock.type, doc="the socket type") 214 proto = property(lambda self: self._sock.proto, doc="the socket protocol") 215 216 _s = ("def %s(self, *args): return self._sock.%s(*args)\n\n" 217 "%s.__doc__ = _realsocket.%s.__doc__\n") 218 for _m in _socketmethods: 219 exec _s % (_m, _m, _m, _m) 220 del _m, _s 221 222socket = SocketType = _socketobject 223 224class _fileobject(object): 225 """Faux file object attached to a socket object.""" 226 227 default_bufsize = 8192 228 name = "<socket>" 229 230 __slots__ = ["mode", "bufsize", "softspace", 231 # "closed" is a property, see below 232 "_sock", "_rbufsize", "_wbufsize", "_rbuf", "_wbuf", "_wbuf_len", 233 "_close"] 234 235 def __init__(self, sock, mode='rb', bufsize=-1, close=False): 236 self._sock = sock 237 self.mode = mode # Not actually used in this version 238 if bufsize < 0: 239 bufsize = self.default_bufsize 240 self.bufsize = bufsize 241 self.softspace = False 242 # _rbufsize is the suggested recv buffer size. It is *strictly* 243 # obeyed within readline() for recv calls. If it is larger than 244 # default_bufsize it will be used for recv calls within read(). 245 if bufsize == 0: 246 self._rbufsize = 1 247 elif bufsize == 1: 248 self._rbufsize = self.default_bufsize 249 else: 250 self._rbufsize = bufsize 251 self._wbufsize = bufsize 252 # We use StringIO for the read buffer to avoid holding a list 253 # of variously sized string objects which have been known to 254 # fragment the heap due to how they are malloc()ed and often 255 # realloc()ed down much smaller than their original allocation. 256 self._rbuf = StringIO() 257 self._wbuf = [] # A list of strings 258 self._wbuf_len = 0 259 self._close = close 260 261 def _getclosed(self): 262 return self._sock is None 263 closed = property(_getclosed, doc="True if the file is closed") 264 265 def close(self): 266 try: 267 if self._sock: 268 self.flush() 269 finally: 270 if self._close: 271 self._sock.close() 272 self._sock = None 273 274 def __del__(self): 275 try: 276 self.close() 277 except: 278 # close() may fail if __init__ didn't complete 279 pass 280 281 def flush(self): 282 if self._wbuf: 283 buffer = "".join(self._wbuf) 284 self._wbuf = [] 285 self._wbuf_len = 0 286 self._sock.sendall(buffer) 287 288 def fileno(self): 289 return self._sock.fileno() 290 291 def write(self, data): 292 data = str(data) # XXX Should really reject non-string non-buffers 293 if not data: 294 return 295 self._wbuf.append(data) 296 self._wbuf_len += len(data) 297 if (self._wbufsize == 0 or 298 self._wbufsize == 1 and '\n' in data or 299 self._wbuf_len >= self._wbufsize): 300 self.flush() 301 302 def writelines(self, list): 303 # XXX We could do better here for very long lists 304 # XXX Should really reject non-string non-buffers 305 lines = filter(None, map(str, list)) 306 self._wbuf_len += sum(map(len, lines)) 307 self._wbuf.extend(lines) 308 if (self._wbufsize <= 1 or 309 self._wbuf_len >= self._wbufsize): 310 self.flush() 311 312 def _get_wbuf_len(self): 313 return self._wbuf_len 314 315 def read(self, size=-1): 316 # Use max, disallow tiny reads in a loop as they are very inefficient. 317 # We never leave read() with any leftover data from a new recv() call 318 # in our internal buffer. 319 rbufsize = max(self._rbufsize, self.default_bufsize) 320 # Our use of StringIO rather than lists of string objects returned by 321 # recv() minimizes memory usage and fragmentation that occurs when 322 # rbufsize is large compared to the typical return value of recv(). 323 buf = self._rbuf 324 buf.seek(0, 2) # seek end 325 if size < 0: 326 # Read until EOF 327 self._rbuf = StringIO() # reset _rbuf. we consume it via buf. 328 while True: 329 data = self._sock.recv(rbufsize) 330 if not data: 331 break 332 buf.write(data) 333 return buf.getvalue() 334 else: 335 # Read until size bytes or EOF seen, whichever comes first 336 buf_len = buf.tell() 337 if buf_len >= size: 338 # Already have size bytes in our buffer? Extract and return. 339 buf.seek(0) 340 rv = buf.read(size) 341 self._rbuf = StringIO() 342 self._rbuf.write(buf.read()) 343 return rv 344 345 self._rbuf = StringIO() # reset _rbuf. we consume it via buf. 346 while True: 347 left = size - buf_len 348 # recv() will malloc the amount of memory given as its 349 # parameter even though it often returns much less data 350 # than that. The returned data string is short lived 351 # as we copy it into a StringIO and free it. This avoids 352 # fragmentation issues on many platforms. 353 data = self._sock.recv(left) 354 if not data: 355 break 356 n = len(data) 357 if n == size and not buf_len: 358 # Shortcut. Avoid buffer data copies when: 359 # - We have no data in our buffer. 360 # AND 361 # - Our call to recv returned exactly the 362 # number of bytes we were asked to read. 363 return data 364 if n == left: 365 buf.write(data) 366 del data # explicit free 367 break 368 assert n <= left, "recv(%d) returned %d bytes" % (left, n) 369 buf.write(data) 370 buf_len += n 371 del data # explicit free 372 #assert buf_len == buf.tell() 373 return buf.getvalue() 374 375 def readline(self, size=-1): 376 buf = self._rbuf 377 buf.seek(0, 2) # seek end 378 if buf.tell() > 0: 379 # check if we already have it in our buffer 380 buf.seek(0) 381 bline = buf.readline(size) 382 if bline.endswith('\n') or len(bline) == size: 383 self._rbuf = StringIO() 384 self._rbuf.write(buf.read()) 385 return bline 386 del bline 387 if size < 0: 388 # Read until \n or EOF, whichever comes first 389 if self._rbufsize <= 1: 390 # Speed up unbuffered case 391 buf.seek(0) 392 buffers = [buf.read()] 393 self._rbuf = StringIO() # reset _rbuf. we consume it via buf. 394 data = None 395 recv = self._sock.recv 396 while data != "\n": 397 data = recv(1) 398 if not data: 399 break 400 buffers.append(data) 401 return "".join(buffers) 402 403 buf.seek(0, 2) # seek end 404 self._rbuf = StringIO() # reset _rbuf. we consume it via buf. 405 while True: 406 data = self._sock.recv(self._rbufsize) 407 if not data: 408 break 409 nl = data.find('\n') 410 if nl >= 0: 411 nl += 1 412 buf.write(data[:nl]) 413 self._rbuf.write(data[nl:]) 414 del data 415 break 416 buf.write(data) 417 return buf.getvalue() 418 else: 419 # Read until size bytes or \n or EOF seen, whichever comes first 420 buf.seek(0, 2) # seek end 421 buf_len = buf.tell() 422 if buf_len >= size: 423 buf.seek(0) 424 rv = buf.read(size) 425 self._rbuf = StringIO() 426 self._rbuf.write(buf.read()) 427 return rv 428 self._rbuf = StringIO() # reset _rbuf. we consume it via buf. 429 while True: 430 data = self._sock.recv(self._rbufsize) 431 if not data: 432 break 433 left = size - buf_len 434 # did we just receive a newline? 435 nl = data.find('\n', 0, left) 436 if nl >= 0: 437 nl += 1 438 # save the excess data to _rbuf 439 self._rbuf.write(data[nl:]) 440 if buf_len: 441 buf.write(data[:nl]) 442 break 443 else: 444 # Shortcut. Avoid data copy through buf when returning 445 # a substring of our first recv(). 446 return data[:nl] 447 n = len(data) 448 if n == size and not buf_len: 449 # Shortcut. Avoid data copy through buf when 450 # returning exactly all of our first recv(). 451 return data 452 if n >= left: 453 buf.write(data[:left]) 454 self._rbuf.write(data[left:]) 455 break 456 buf.write(data) 457 buf_len += n 458 #assert buf_len == buf.tell() 459 return buf.getvalue() 460 461 def readlines(self, sizehint=0): 462 total = 0 463 list = [] 464 while True: 465 line = self.readline() 466 if not line: 467 break 468 list.append(line) 469 total += len(line) 470 if sizehint and total >= sizehint: 471 break 472 return list 473 474 # Iterator protocols 475 476 def __iter__(self): 477 return self 478 479 def next(self): 480 line = self.readline() 481 if not line: 482 raise StopIteration 483 return line 484 485_GLOBAL_DEFAULT_TIMEOUT = object() 486 487def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT): 488 """Connect to *address* and return the socket object. 489 490 Convenience function. Connect to *address* (a 2-tuple ``(host, 491 port)``) and return the socket object. Passing the optional 492 *timeout* parameter will set the timeout on the socket instance 493 before attempting to connect. If no *timeout* is supplied, the 494 global default timeout setting returned by :func:`getdefaulttimeout` 495 is used. 496 """ 497 498 msg = "getaddrinfo returns an empty list" 499 host, port = address 500 for res in getaddrinfo(host, port, 0, SOCK_STREAM): 501 af, socktype, proto, canonname, sa = res 502 sock = None 503 try: 504 sock = socket(af, socktype, proto) 505 if timeout is not _GLOBAL_DEFAULT_TIMEOUT: 506 sock.settimeout(timeout) 507 sock.connect(sa) 508 return sock 509 510 except error, msg: 511 if sock is not None: 512 sock.close() 513 514 raise error, msg