1 # Wrapper module for _socket, providing some additional facilities
2 # implemented in Python.
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.
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
29 [*] not available on all platforms!
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
39 AF_INET, AF_UNIX -- socket domains (first argument to socket() call)
40 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument)
42 Many other constants may be defined; these may be used in calls to
43 the setsockopt() and getsockopt() methods.
48 from functools
import partial
49 from new
import instancemethod
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
)
65 # we need to import the same constants we used to...
66 from _ssl
import SSLError
as sslerror
71 SSL_ERROR_ZERO_RETURN
, \
72 SSL_ERROR_WANT_READ
, \
73 SSL_ERROR_WANT_WRITE
, \
74 SSL_ERROR_WANT_X509_LOOKUP
, \
77 SSL_ERROR_WANT_CONNECT
, \
79 SSL_ERROR_INVALID_ERROR_CODE
81 import os
, sys
, warnings
84 from cStringIO
import StringIO
86 from StringIO
import StringIO
89 from errno
import EBADF
93 __all__
= ["getfqdn", "create_connection"]
94 __all__
.extend(os
._get
_exports
_list
(_socket
))
100 if sys
.platform
.lower().startswith("win"):
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")
121 def getfqdn(name
=''):
122 """Get fully qualified domain name from name.
124 An empty argument is interpreted as meaning the local host.
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.
131 if not name
or name
== '0.0.0.0':
134 hostname
, aliases
, ipaddrs
= gethostbyaddr(name
)
138 aliases
.insert(0, hostname
)
148 'bind', 'connect', 'connect_ex', 'fileno', 'listen',
149 'getpeername', 'getsockname', 'getsockopt', 'setsockopt',
150 'sendall', 'setblocking',
151 'settimeout', 'gettimeout', 'shutdown')
154 _socketmethods
= _socketmethods
+ ('ioctl',)
156 if sys
.platform
== "riscos":
157 _socketmethods
= _socketmethods
+ ('sleeptaskw',)
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",
164 class _closedsocket(object):
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
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):
178 __doc__
= _realsocket
.__doc
__
180 __slots__
= ["_sock", "__weakref__"] + list(_delegate_methods
)
182 def __init__(self
, family
=AF_INET
, type=SOCK_STREAM
, proto
=0, _sock
=None):
184 _sock
= _realsocket(family
, type, proto
)
186 for method
in _delegate_methods
:
187 setattr(self
, method
, getattr(_sock
, method
))
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
__
197 sock
, addr
= self
._sock
.accept()
198 return _socketobject(_sock
=sock
), addr
199 accept
.__doc
__ = _realsocket
.accept
.__doc
__
202 """dup() -> socket object
204 Return a new socket object connected to the same system resource."""
205 return _socketobject(_sock
=self
._sock
)
207 def makefile(self
, mode
='r', bufsize
=-1):
208 """makefile([mode[, bufsize]]) -> file object
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
)
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")
218 def meth(name
,self
,*args
):
219 return getattr(self
._sock
,name
)(*args
)
221 for _m
in _socketmethods
:
224 p
.__doc
__ = getattr(_realsocket
,_m
).__doc
__
225 m
= instancemethod(p
,None,_socketobject
)
226 setattr(_socketobject
,_m
,m
)
228 socket
= SocketType
= _socketobject
230 class _fileobject(object):
231 """Faux file object attached to a socket object."""
233 default_bufsize
= 8192
236 __slots__
= ["mode", "bufsize", "softspace",
237 # "closed" is a property, see below
238 "_sock", "_rbufsize", "_wbufsize", "_rbuf", "_wbuf",
241 def __init__(self
, sock
, mode
='rb', bufsize
=-1, close
=False):
243 self
.mode
= mode
# Not actually used in this version
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().
254 self
._rbufsize
= self
.default_bufsize
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
266 def _getclosed(self
):
267 return self
._sock
is None
268 closed
= property(_getclosed
, doc
="True if the file is closed")
283 # close() may fail if __init__ didn't complete
288 buffer = "".join(self
._wbuf
)
290 self
._sock
.sendall(buffer)
293 return self
._sock
.fileno()
295 def write(self
, data
):
296 data
= str(data
) # XXX Should really reject non-string non-buffers
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
):
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
):
313 def _get_wbuf_len(self
):
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().
328 buf
.seek(0, 2) # seek end
331 self
._rbuf
= StringIO() # reset _rbuf. we consume it via buf.
333 data
= self
._sock
.recv(rbufsize
)
337 return buf
.getvalue()
339 # Read until size bytes or EOF seen, whichever comes first
342 # Already have size bytes in our buffer? Extract and return.
345 self
._rbuf
= StringIO()
346 self
._rbuf
.write(buf
.read())
349 self
._rbuf
= StringIO() # reset _rbuf. we consume it via buf.
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
)
361 if n
== size
and not buf_len
:
362 # Shortcut. Avoid buffer data copies when:
363 # - We have no data in our buffer.
365 # - Our call to recv returned exactly the
366 # number of bytes we were asked to read.
370 del data
# explicit free
372 assert n
<= left
, "recv(%d) returned %d bytes" % (left
, n
)
375 del data
# explicit free
376 #assert buf_len == buf.tell()
377 return buf
.getvalue()
379 def readline(self
, size
=-1):
381 buf
.seek(0, 2) # seek end
383 # check if we already have it in our buffer
385 bline
= buf
.readline(size
)
386 if bline
.endswith('\n') or len(bline
) == size
:
387 self
._rbuf
= StringIO()
388 self
._rbuf
.write(buf
.read())
392 # Read until \n or EOF, whichever comes first
393 if self
._rbufsize
<= 1:
394 # Speed up unbuffered case
396 buffers
= [buf
.read()]
397 self
._rbuf
= StringIO() # reset _rbuf. we consume it via buf.
399 recv
= self
._sock
.recv
405 return "".join(buffers
)
407 buf
.seek(0, 2) # seek end
408 self
._rbuf
= StringIO() # reset _rbuf. we consume it via buf.
410 data
= self
._sock
.recv(self
._rbufsize
)
417 self
._rbuf
.write(data
[nl
:])
421 return buf
.getvalue()
423 # Read until size bytes or \n or EOF seen, whichever comes first
424 buf
.seek(0, 2) # seek end
429 self
._rbuf
= StringIO()
430 self
._rbuf
.write(buf
.read())
432 self
._rbuf
= StringIO() # reset _rbuf. we consume it via buf.
434 data
= self
._sock
.recv(self
._rbufsize
)
437 left
= size
- buf_len
438 # did we just receive a newline?
439 nl
= data
.find('\n', 0, left
)
442 # save the excess data to _rbuf
443 self
._rbuf
.write(data
[nl
:])
448 # Shortcut. Avoid data copy through buf when returning
449 # a substring of our first recv().
452 if n
== size
and not buf_len
:
453 # Shortcut. Avoid data copy through buf when
454 # returning exactly all of our first recv().
457 buf
.write(data
[:left
])
458 self
._rbuf
.write(data
[left
:])
462 #assert buf_len == buf.tell()
463 return buf
.getvalue()
465 def readlines(self
, sizehint
=0):
469 line
= self
.readline()
474 if sizehint
and total
>= sizehint
:
484 line
= self
.readline()
489 _GLOBAL_DEFAULT_TIMEOUT
= object()
491 def create_connection(address
, timeout
=_GLOBAL_DEFAULT_TIMEOUT
):
492 """Connect to *address* and return the socket object.
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`
502 msg
= "getaddrinfo returns an empty list"
504 for res
in getaddrinfo(host
, port
, 0, SOCK_STREAM
):
505 af
, socktype
, proto
, canonname
, sa
= res
508 sock
= socket(af
, socktype
, proto
)
509 if timeout
is not _GLOBAL_DEFAULT_TIMEOUT
:
510 sock
.settimeout(timeout
)