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