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