Lib/socket.py

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