mpd.py: updating _connect_tcp() with new socket code

_connect_tcp() is largely based on Python's socket.create_connection().
Previously, this code contained two bugs related to raising exceptions.

The first bug was introduced by my clumsy attempt to update the code to use
the new preferred method of raising exceptions (the same mistake was made
in the Python 3 port of the socket module).  Instead of raising
socket.error with the value of the original exception, socket.error was
raised with the original exception as the value of the new exception, thus
nesting an exception within an exception.  Python 3.1.3 fixed this by
simply re-raising the original exception.

The second bug is hit when getaddrinfo() returns an empty list.  A
socket.error is raised with a single string as its argument, instead of a
2-tuple as required by its parent class, IOError.  This bug continues to
persist in Python 3.1.3 as well as the latest svn tree.

This commit updates _connect_tcp() to be a nearly identical copy of the
Python 3.1.3 version of socket.create_connection(), except that
ConnectionError is raised when getaddrinfo() returns an empty list.

removing TODO.txt

I maintain a separate personal TODO file for python-mpd which supercedes
this one, but it's really not fit for inclusion.

CHANGES.txt: adding changes in prep for 0.3.0 release

mpd.py: clear command list if an exception is raised

This fixes a very longstanding bug where an MPD command error would raise
an exception, but not clear the command list. This would prevent further
commands from being executed until the command list was completed, which
was impossible since the MPD command error broke out of the command list
on the server side.

mpd.py: unset iterating flag if an exception is raised

This fixes a bug where an MPD command error would raise an exception, but
leave the iterating flag set, preventing further commands from being
executed.

mpd.py: don't allow command_list_end if already iterating

mpd.py: set iterating flag before returning iterator

mpd.py: check if iterating before fetching response

If an iterator is currently in progress, all functions which fetch a
response (such as <cmd>() and fetch_<cmd>()) will be disabled, as well as
command lists.  This makes iterators much more reliable by preventing code
from reading a response while an iterator is trying to read another
response.  Previously this was allowed, and would corrupt the library state
by providing false responses to both the iterator and the code trying to
fetch a different response.

mpd.py: remove superfluous StopIteration exceptions

README.txt: give an example that actually works

updating copyright years

setup.py: updating URL

mpd.py: adding fileno() to export socket FD

This allows access to the socket FD for polling if it can be written
to/read from.  This is useful with, for example, the idle command.  Simply
call send_idle(), poll the socket FD with select/poll/etc to check if it's
ready for reading, and if it is, call fetch_idle() to see what changed.
Note that select et al. call fileno() on any objects you pass to them, so
you can simply pass the MPDClient instance itself to these functions
instead of the FD returned by fileno().

mpd.py: tidying up _execute()

mpd.py: adding support for asynchronous commands

send_<cmd>/fetch_<cmd> may now be used to send/fetch the command <cmd>.
fetch_<cmd> may be called multiple times to queue up various commands, but
they must be fetched in the same order they were sent.  This functionality
cannot be mixed with command lists.

mpd.py: don't use has_key()

key in obj is easier to read, and even a little faster.

doc/commands.txt: updating to match the new internal API

mpd.py: internal API cleanup

Function names should be more readable now, and the new naming scheme will
fit in better with the upcoming asynchronous API.

mpd.py: raise ConnectionError if unix sockets aren't supported

preliminary unix socket support

If the host passed to connect() starts with a "/", then a connection
attempt is made to the unix socket at the specified path.  The port
argument is currently still required, but will be ignored.  Attempting to
connect to a unix socket on Windows will raise an AttributeError (because
socket.AF_UNIX isn't defined), however this will later be changed.

adding consume and single commands

adding idle and noidle commands

Note that these commands aren't very usable in their current form.  idle()
blocks while waiting for events, and will thus hang if none are received.
Calling noidle() from another thread will cause idle() to return, but
python-mpd isn't considered re-entrant, so sharing instances between
threads isn't recommended.

adding listplaylists command

rearranging commands to match new protocol documentation

setup.py: incrementing version number to 0.2.1

CHANGES.txt: document change in previous commit

mpd.py: adding a workaround for systems missing socket.AI_ADDRCONFIG

Python on Windows doesn't define socket.AI_ADDRCONFIG.  This is likely
because the flag is only supported by getaddrinfo() on Vista or later.

setup.py: incrementing version number to 0.2.0

mpd.py: catch all exceptions raised by _hello()

I normally consider it bad form to catch all exceptions, since it can
result in lost KeyboardInterrupts.  But in this case we re-raise the
exception after cleaning up, so it's ok.

While _hello() itself only raises socket.error or an MPDError subclass, a
KeyboardInterrupt would previously go uncaught.  Since the connection was
never cleaned up, it could be left in an unusable state.  So just
disconnect on all exceptions instead.

TODO.txt: removing pre- and post-release sections

mpd.py: changing exception raising to comply with the Python Style Guide

mpd.py: strip trailing \n from MPD's hello line for a nicer error message

mpd.py: reset to disconnected state if _hello() fails in connect()

TODO.txt: removing completed TODO item

CHANGES.txt: document change in previous commit

mpd.py: loop over addresses returned by getaddrinfo to connect to

This allows us to support IPv6 and multi-homed hostnames.  getaddrinfo is
called with the same flags as libmpdclient uses, making address resolution
consistent between the two.

CHANGES.txt: document change in previous commit

mpd.py: raise ConnectionError if connect() is called when already connected

mpd.py: use a separate file object for reading and writing sockets

This is to make it easier to read command output from a file instead of a
socket.  Useful for testing and benchmarking.

mpd.py: raise ConnectionError when trying to use an unconnected socket

ConnectionError will now be raised when trying to read from/write to a
socket before calling connect() or after calling disconnect().  In the past
it would try to complete the operation on the unconnected socket, resulting
in a socket.error exception.

TODO.txt: cleaning up and splitting into pre- and post-release sections

TODO.txt: changing header for consistency

adding CHANGES.txt

TODO.txt: removing completed TODO item

mpd.py: raise ConnectionError on EOF

TODO.txt: adding TODO item

mpd.py: making _getitem return None if no item is returned

update and addid should normally always return a single item, so previously
an exception was raised if we got nothing.  However, when used in a
command_list, only the *last* call to update will return an item.  So
return None instead of raising an exception if we get nothing.

setup.py: commenting out license/platforms

The license and platforms fields should be filled out *only* if appropriate
classifiers don't already exist (which in our case, they do).

MANIFEST.in: exclude setup.cfg

Like MANIFEST.in, setup.cfg is (currently) only used for building
distributions.  So don't include it in the distribution itself.

mpd.py: adding one line description at top of file

TODO.txt: removing completed TODO item and pre-release section

adding setup.py, setup.cfg, and MANIFEST.in

TODO.txt: removing a completed TODO item

adding README.txt

TODO.txt: changing a couple TODO items

addding doc/commands.txt to document supported commands

renaming TODO to TODO.txt

TODO: removing completed TODO item

adding LICENSE.txt and a copyright notice to mpd.py

mpd.py: removing shebang line

TODO: adding pre- and post-release sections, and a few more TODO items

TODO: adding TODO item

moving TODO list to separate TODO file

remove argument checking/parsing TODO item

mpd already does a much better job of validating arguments than we ever
could, so no point in us doing it too.  Parsing arguments is also rather
pointless, as all arguments are coerced to strings before escaping anyway.

return an empty dict if no object is read

adding command_list support

initial commit