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
  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", "_wbuf_len",
 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._wbuf_len = 0
 265         self._close = close
 266
 267     def _getclosed(self):
 268         return self._sock is None
 269     closed = property(_getclosed, doc="True if the file is closed")
 270
 271     def close(self):
 272         try:
 273             if self._sock:
 274                 self.flush()
 275         finally:
 276             if self._close:
 277                 self._sock.close()
 278             self._sock = None
 279
 280     def __del__(self):
 281         try:
 282             self.close()
 283         except:
 284             # close() may fail if __init__ didn't complete
 285             pass
 286
 287     def flush(self):
 288         if self._wbuf:
 289             buffer = "".join(self._wbuf)
 290             self._wbuf = []
 291             self._wbuf_len = 0
 292             self._sock.sendall(buffer)
 293
 294     def fileno(self):
 295         return self._sock.fileno()
 296
 297     def write(self, data):
 298         data = str(data) # XXX Should really reject non-string non-buffers
 299         if not data:
 300             return
 301         self._wbuf.append(data)
 302         self._wbuf_len += len(data)
 303         if (self._wbufsize == 0 or
 304             self._wbufsize == 1 and '\n' in data or
 305             self._wbuf_len >= self._wbufsize):
 306             self.flush()
 307
 308     def writelines(self, list):
 309         # XXX We could do better here for very long lists
 310         # XXX Should really reject non-string non-buffers
 311         lines = filter(None, map(str, list))
 312         self._wbuf_len += sum(map(len, lines))
 313         self._wbuf.extend(lines)
 314         if (self._wbufsize <= 1 or
 315             self._wbuf_len >= self._wbufsize):
 316             self.flush()
 317
 318     def read(self, size=-1):
 319         # Use max, disallow tiny reads in a loop as they are very inefficient.
 320         # We never leave read() with any leftover data from a new recv() call
 321         # in our internal buffer.
 322         rbufsize = max(self._rbufsize, self.default_bufsize)
 323         # Our use of StringIO rather than lists of string objects returned by
 324         # recv() minimizes memory usage and fragmentation that occurs when
 325         # rbufsize is large compared to the typical return value of recv().
 326         buf = self._rbuf
 327         buf.seek(0, 2)  # seek end
 328         if size < 0:
 329             # Read until EOF
 330             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.
 331             while True:
 332                 data = self._sock.recv(rbufsize)
 333                 if not data:
 334                     break
 335                 buf.write(data)
 336             return buf.getvalue()
 337         else:
 338             # Read until size bytes or EOF seen, whichever comes first
 339             buf_len = buf.tell()
 340             if buf_len >= size:
 341                 # Already have size bytes in our buffer?  Extract and return.
 342                 buf.seek(0)
 343                 rv = buf.read(size)
 344                 self._rbuf = StringIO()
 345                 self._rbuf.write(buf.read())
 346                 return rv
 347
 348             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.
 349             while True:
 350                 left = size - buf_len
 351                 # recv() will malloc the amount of memory given as its
 352                 # parameter even though it often returns much less data
 353                 # than that.  The returned data string is short lived
 354                 # as we copy it into a StringIO and free it.  This avoids
 355                 # fragmentation issues on many platforms.
 356                 data = self._sock.recv(left)
 357                 if not data:
 358                     break
 359                 n = len(data)
 360                 if n == size and not buf_len:
 361                     # Shortcut.  Avoid buffer data copies when:
 362                     # - We have no data in our buffer.
 363                     # AND
 364                     # - Our call to recv returned exactly the
 365                     #   number of bytes we were asked to read.
 366                     return data
 367                 if n == left:
 368                     buf.write(data)
 369                     del data  # explicit free
 370                     break
 371                 assert n <= left, "recv(%d) returned %d bytes" % (left, n)
 372                 buf.write(data)
 373                 buf_len += n
 374                 del data  # explicit free
 375                 #assert buf_len == buf.tell()
 376             return buf.getvalue()
 377
 378     def readline(self, size=-1):
 379         buf = self._rbuf
 380         buf.seek(0, 2)  # seek end
 381         if buf.tell() > 0:
 382             # check if we already have it in our buffer
 383             buf.seek(0)
 384             bline = buf.readline(size)
 385             if bline.endswith('\n') or len(bline) == size:
 386                 self._rbuf = StringIO()
 387                 self._rbuf.write(buf.read())
 388                 return bline
 389             del bline
 390         if size < 0:
 391             # Read until \n or EOF, whichever comes first
 392             if self._rbufsize <= 1:
 393                 # Speed up unbuffered case
 394                 buf.seek(0)
 395                 buffers = [buf.read()]
 396                 self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.
 397                 data = None
 398                 recv = self._sock.recv
 399                 while data != "\n":
 400                     data = recv(1)
 401                     if not data:
 402                         break
 403                     buffers.append(data)
 404                 return "".join(buffers)
 405
 406             buf.seek(0, 2)  # seek end
 407             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.
 408             while True:
 409                 data = self._sock.recv(self._rbufsize)
 410                 if not data:
 411                     break
 412                 nl = data.find('\n')
 413                 if nl >= 0:
 414                     nl += 1
 415                     buf.write(data[:nl])
 416                     self._rbuf.write(data[nl:])
 417                     del data
 418                     break
 419                 buf.write(data)
 420             return buf.getvalue()
 421         else:
 422             # Read until size bytes or \n or EOF seen, whichever comes first
 423             buf.seek(0, 2)  # seek end
 424             buf_len = buf.tell()
 425             if buf_len >= size:
 426                 buf.seek(0)
 427                 rv = buf.read(size)
 428                 self._rbuf = StringIO()
 429                 self._rbuf.write(buf.read())
 430                 return rv
 431             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.
 432             while True:
 433                 data = self._sock.recv(self._rbufsize)
 434                 if not data:
 435                     break
 436                 left = size - buf_len
 437                 # did we just receive a newline?
 438                 nl = data.find('\n', 0, left)
 439                 if nl >= 0:
 440                     nl += 1
 441                     # save the excess data to _rbuf
 442                     self._rbuf.write(data[nl:])
 443                     if buf_len:
 444                         buf.write(data[:nl])
 445                         break
 446                     else:
 447                         # Shortcut.  Avoid data copy through buf when returning
 448                         # a substring of our first recv().
 449                         return data[:nl]
 450                 n = len(data)
 451                 if n == size and not buf_len:
 452                     # Shortcut.  Avoid data copy through buf when
 453                     # returning exactly all of our first recv().
 454                     return data
 455                 if n >= left:
 456                     buf.write(data[:left])
 457                     self._rbuf.write(data[left:])
 458                     break
 459                 buf.write(data)
 460                 buf_len += n
 461                 #assert buf_len == buf.tell()
 462             return buf.getvalue()
 463
 464     def readlines(self, sizehint=0):
 465         total = 0
 466         list = []
 467         while True:
 468             line = self.readline()
 469             if not line:
 470                 break
 471             list.append(line)
 472             total += len(line)
 473             if sizehint and total >= sizehint:
 474                 break
 475         return list
 476
 477     # Iterator protocols
 478
 479     def __iter__(self):
 480         return self
 481
 482     def next(self):
 483         line = self.readline()
 484         if not line:
 485             raise StopIteration
 486         return line
 487
 488 _GLOBAL_DEFAULT_TIMEOUT = object()
 489
 490 def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT):
 491     """Connect to *address* and return the socket object.
 492
 493     Convenience function.  Connect to *address* (a 2-tuple ``(host,
 494     port)``) and return the socket object.  Passing the optional
 495     *timeout* parameter will set the timeout on the socket instance
 496     before attempting to connect.  If no *timeout* is supplied, the
 497     global default timeout setting returned by :func:`getdefaulttimeout`
 498     is used.
 499     """
 500
 501     msg = "getaddrinfo returns an empty list"
 502     host, port = address
 503     for res in getaddrinfo(host, port, 0, SOCK_STREAM):
 504         af, socktype, proto, canonname, sa = res
 505         sock = None
 506         try:
 507             sock = socket(af, socktype, proto)
 508             if timeout is not _GLOBAL_DEFAULT_TIMEOUT:
 509                 sock.settimeout(timeout)
 510             sock.connect(sa)
 511             return sock
 512
 513         except error, msg:
 514             if sock is not None:
 515                 sock.close()
 516
 517     raise error, msg