Home | History | Annotate | Download | only in Lib
      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, _closedsocket=_closedsocket,
    193               _delegate_methods=_delegate_methods, setattr=setattr):
    194         # This function should not reference any globals. See issue #808164.

    195         self._sock = _closedsocket()
    196         dummy = self._sock._dummy
    197         for method in _delegate_methods:
    198             setattr(self, method, dummy)
    199     close.__doc__ = _realsocket.close.__doc__
    200 
    201     def accept(self):
    202         sock, addr = self._sock.accept()
    203         return _socketobject(_sock=sock), addr
    204     accept.__doc__ = _realsocket.accept.__doc__
    205 
    206     def dup(self):
    207         """dup() -> socket object
    208 
    209         Return a new socket object connected to the same system resource."""
    210         return _socketobject(_sock=self._sock)
    211 
    212     def makefile(self, mode='r', bufsize=-1):
    213         """makefile([mode[, bufsize]]) -> file object
    214 
    215         Return a regular file object corresponding to the socket.  The mode
    216         and bufsize arguments are as for the built-in open() function."""
    217         return _fileobject(self._sock, mode, bufsize)
    218 
    219     family = property(lambda self: self._sock.family, doc="the socket family")
    220     type = property(lambda self: self._sock.type, doc="the socket type")
    221     proto = property(lambda self: self._sock.proto, doc="the socket protocol")
    222 
    223 def meth(name,self,*args):
    224     return getattr(self._sock,name)(*args)
    225 
    226 for _m in _socketmethods:
    227     p = partial(meth,_m)
    228     p.__name__ = _m
    229     p.__doc__ = getattr(_realsocket,_m).__doc__
    230     m = MethodType(p,None,_socketobject)
    231     setattr(_socketobject,_m,m)
    232 
    233 socket = SocketType = _socketobject
    234 
    235 class _fileobject(object):
    236     """Faux file object attached to a socket object."""
    237 
    238     default_bufsize = 8192
    239     name = "<socket>"
    240 
    241     __slots__ = ["mode", "bufsize", "softspace",
    242                  # "closed" is a property, see below

    243                  "_sock", "_rbufsize", "_wbufsize", "_rbuf", "_wbuf", "_wbuf_len",
    244                  "_close"]
    245 
    246     def __init__(self, sock, mode='rb', bufsize=-1, close=False):
    247         self._sock = sock
    248         self.mode = mode # Not actually used in this version

    249         if bufsize < 0:
    250             bufsize = self.default_bufsize
    251         self.bufsize = bufsize
    252         self.softspace = False
    253         # _rbufsize is the suggested recv buffer size.  It is *strictly*

    254         # obeyed within readline() for recv calls.  If it is larger than

    255         # default_bufsize it will be used for recv calls within read().

    256         if bufsize == 0:
    257             self._rbufsize = 1
    258         elif bufsize == 1:
    259             self._rbufsize = self.default_bufsize
    260         else:
    261             self._rbufsize = bufsize
    262         self._wbufsize = bufsize
    263         # We use StringIO for the read buffer to avoid holding a list

    264         # of variously sized string objects which have been known to

    265         # fragment the heap due to how they are malloc()ed and often

    266         # realloc()ed down much smaller than their original allocation.

    267         self._rbuf = StringIO()
    268         self._wbuf = [] # A list of strings

    269         self._wbuf_len = 0
    270         self._close = close
    271 
    272     def _getclosed(self):
    273         return self._sock is None
    274     closed = property(_getclosed, doc="True if the file is closed")
    275 
    276     def close(self):
    277         try:
    278             if self._sock:
    279                 self.flush()
    280         finally:
    281             if self._close:
    282                 self._sock.close()
    283             self._sock = None
    284 
    285     def __del__(self):
    286         try:
    287             self.close()
    288         except:
    289             # close() may fail if __init__ didn't complete

    290             pass
    291 
    292     def flush(self):
    293         if self._wbuf:
    294             data = "".join(self._wbuf)
    295             self._wbuf = []
    296             self._wbuf_len = 0
    297             buffer_size = max(self._rbufsize, self.default_bufsize)
    298             data_size = len(data)
    299             write_offset = 0
    300             view = memoryview(data)
    301             try:
    302                 while write_offset < data_size:
    303                     self._sock.sendall(view[write_offset:write_offset+buffer_size])
    304                     write_offset += buffer_size
    305             finally:
    306                 if write_offset < data_size:
    307                     remainder = data[write_offset:]
    308                     del view, data  # explicit free

    309                     self._wbuf.append(remainder)
    310                     self._wbuf_len = len(remainder)
    311 
    312     def fileno(self):
    313         return self._sock.fileno()
    314 
    315     def write(self, data):
    316         data = str(data) # XXX Should really reject non-string non-buffers

    317         if not data:
    318             return
    319         self._wbuf.append(data)
    320         self._wbuf_len += len(data)
    321         if (self._wbufsize == 0 or
    322             self._wbufsize == 1 and '\n' in data or
    323             self._wbuf_len >= self._wbufsize):
    324             self.flush()
    325 
    326     def writelines(self, list):
    327         # XXX We could do better here for very long lists

    328         # XXX Should really reject non-string non-buffers

    329         lines = filter(None, map(str, list))
    330         self._wbuf_len += sum(map(len, lines))
    331         self._wbuf.extend(lines)
    332         if (self._wbufsize <= 1 or
    333             self._wbuf_len >= self._wbufsize):
    334             self.flush()
    335 
    336     def read(self, size=-1):
    337         # Use max, disallow tiny reads in a loop as they are very inefficient.

    338         # We never leave read() with any leftover data from a new recv() call

    339         # in our internal buffer.

    340         rbufsize = max(self._rbufsize, self.default_bufsize)
    341         # Our use of StringIO rather than lists of string objects returned by

    342         # recv() minimizes memory usage and fragmentation that occurs when

    343         # rbufsize is large compared to the typical return value of recv().

    344         buf = self._rbuf
    345         buf.seek(0, 2)  # seek end

    346         if size < 0:
    347             # Read until EOF

    348             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.

    349             while True:
    350                 try:
    351                     data = self._sock.recv(rbufsize)
    352                 except error, e:
    353                     if e.args[0] == EINTR:
    354                         continue
    355                     raise
    356                 if not data:
    357                     break
    358                 buf.write(data)
    359             return buf.getvalue()
    360         else:
    361             # Read until size bytes or EOF seen, whichever comes first

    362             buf_len = buf.tell()
    363             if buf_len >= size:
    364                 # Already have size bytes in our buffer?  Extract and return.

    365                 buf.seek(0)
    366                 rv = buf.read(size)
    367                 self._rbuf = StringIO()
    368                 self._rbuf.write(buf.read())
    369                 return rv
    370 
    371             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.

    372             while True:
    373                 left = size - buf_len
    374                 # recv() will malloc the amount of memory given as its

    375                 # parameter even though it often returns much less data

    376                 # than that.  The returned data string is short lived

    377                 # as we copy it into a StringIO and free it.  This avoids

    378                 # fragmentation issues on many platforms.

    379                 try:
    380                     data = self._sock.recv(left)
    381                 except error, e:
    382                     if e.args[0] == EINTR:
    383                         continue
    384                     raise
    385                 if not data:
    386                     break
    387                 n = len(data)
    388                 if n == size and not buf_len:
    389                     # Shortcut.  Avoid buffer data copies when:

    390                     # - We have no data in our buffer.

    391                     # AND

    392                     # - Our call to recv returned exactly the

    393                     #   number of bytes we were asked to read.

    394                     return data
    395                 if n == left:
    396                     buf.write(data)
    397                     del data  # explicit free

    398                     break
    399                 assert n <= left, "recv(%d) returned %d bytes" % (left, n)
    400                 buf.write(data)
    401                 buf_len += n
    402                 del data  # explicit free

    403                 #assert buf_len == buf.tell()

    404             return buf.getvalue()
    405 
    406     def readline(self, size=-1):
    407         buf = self._rbuf
    408         buf.seek(0, 2)  # seek end

    409         if buf.tell() > 0:
    410             # check if we already have it in our buffer

    411             buf.seek(0)
    412             bline = buf.readline(size)
    413             if bline.endswith('\n') or len(bline) == size:
    414                 self._rbuf = StringIO()
    415                 self._rbuf.write(buf.read())
    416                 return bline
    417             del bline
    418         if size < 0:
    419             # Read until \n or EOF, whichever comes first

    420             if self._rbufsize <= 1:
    421                 # Speed up unbuffered case

    422                 buf.seek(0)
    423                 buffers = [buf.read()]
    424                 self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.

    425                 data = None
    426                 recv = self._sock.recv
    427                 while True:
    428                     try:
    429                         while data != "\n":
    430                             data = recv(1)
    431                             if not data:
    432                                 break
    433                             buffers.append(data)
    434                     except error, e:
    435                         # The try..except to catch EINTR was moved outside the

    436                         # recv loop to avoid the per byte overhead.

    437                         if e.args[0] == EINTR:
    438                             continue
    439                         raise
    440                     break
    441                 return "".join(buffers)
    442 
    443             buf.seek(0, 2)  # seek end

    444             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.

    445             while True:
    446                 try:
    447                     data = self._sock.recv(self._rbufsize)
    448                 except error, e:
    449                     if e.args[0] == EINTR:
    450                         continue
    451                     raise
    452                 if not data:
    453                     break
    454                 nl = data.find('\n')
    455                 if nl >= 0:
    456                     nl += 1
    457                     buf.write(data[:nl])
    458                     self._rbuf.write(data[nl:])
    459                     del data
    460                     break
    461                 buf.write(data)
    462             return buf.getvalue()
    463         else:
    464             # Read until size bytes or \n or EOF seen, whichever comes first

    465             buf.seek(0, 2)  # seek end

    466             buf_len = buf.tell()
    467             if buf_len >= size:
    468                 buf.seek(0)
    469                 rv = buf.read(size)
    470                 self._rbuf = StringIO()
    471                 self._rbuf.write(buf.read())
    472                 return rv
    473             self._rbuf = StringIO()  # reset _rbuf.  we consume it via buf.

    474             while True:
    475                 try:
    476                     data = self._sock.recv(self._rbufsize)
    477                 except error, e:
    478                     if e.args[0] == EINTR:
    479                         continue
    480                     raise
    481                 if not data:
    482                     break
    483                 left = size - buf_len
    484                 # did we just receive a newline?

    485                 nl = data.find('\n', 0, left)
    486                 if nl >= 0:
    487                     nl += 1
    488                     # save the excess data to _rbuf

    489                     self._rbuf.write(data[nl:])
    490                     if buf_len:
    491                         buf.write(data[:nl])
    492                         break
    493                     else:
    494                         # Shortcut.  Avoid data copy through buf when returning

    495                         # a substring of our first recv().

    496                         return data[:nl]
    497                 n = len(data)
    498                 if n == size and not buf_len:
    499                     # Shortcut.  Avoid data copy through buf when

    500                     # returning exactly all of our first recv().

    501                     return data
    502                 if n >= left:
    503                     buf.write(data[:left])
    504                     self._rbuf.write(data[left:])
    505                     break
    506                 buf.write(data)
    507                 buf_len += n
    508                 #assert buf_len == buf.tell()

    509             return buf.getvalue()
    510 
    511     def readlines(self, sizehint=0):
    512         total = 0
    513         list = []
    514         while True:
    515             line = self.readline()
    516             if not line:
    517                 break
    518             list.append(line)
    519             total += len(line)
    520             if sizehint and total >= sizehint:
    521                 break
    522         return list
    523 
    524     # Iterator protocols

    525 
    526     def __iter__(self):
    527         return self
    528 
    529     def next(self):
    530         line = self.readline()
    531         if not line:
    532             raise StopIteration
    533         return line
    534 
    535 _GLOBAL_DEFAULT_TIMEOUT = object()
    536 
    537 def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT,
    538                       source_address=None):
    539     """Connect to *address* and return the socket object.
    540 
    541     Convenience function.  Connect to *address* (a 2-tuple ``(host,
    542     port)``) and return the socket object.  Passing the optional
    543     *timeout* parameter will set the timeout on the socket instance
    544     before attempting to connect.  If no *timeout* is supplied, the
    545     global default timeout setting returned by :func:`getdefaulttimeout`
    546     is used.  If *source_address* is set it must be a tuple of (host, port)
    547     for the socket to bind as a source address before making the connection.
    548     An host of '' or port 0 tells the OS to use the default.
    549     """
    550 
    551     host, port = address
    552     err = None
    553     for res in getaddrinfo(host, port, 0, SOCK_STREAM):
    554         af, socktype, proto, canonname, sa = res
    555         sock = None
    556         try:
    557             sock = socket(af, socktype, proto)
    558             if timeout is not _GLOBAL_DEFAULT_TIMEOUT:
    559                 sock.settimeout(timeout)
    560             if source_address:
    561                 sock.bind(source_address)
    562             sock.connect(sa)
    563             return sock
    564 
    565         except error as _:
    566             err = _
    567             if sock is not None:
    568                 sock.close()
    569 
    570     if err is not None:
    571         raise err
    572     else:
    573         raise error("getaddrinfo returns an empty list")
    574