Errors should never pass silently. I therefore suggest to raise an exception whenever SoCo would previously just return an error code/string.
Absolutely ;) We have been missing proper exceptions. I've looked through the code and I think it looks really good. A few things, suggestions or questions really, came to mind while reading it.
The location of the exceptions. So we only have 2 of them right now, but maybe it would be worth it to move them to a separate file right from the start, also to help in keeping the size of core.py down.
Doc strings. When I first read the code I remember thinking that the doc strings for the soco methods were quite verbose in the explanation of the error handling and that it would to somehow fix that when we introduced exceptions. I'm wondering if it would not actually be ok to replace the entire:
If an error occurs, we'll attempt to parse the error and raise a
SoCoException with the UPnP error code. If that fails, an
UnknownSoCoException with the raw response sent back from the Sonos
speaker will be raised.
Raises SoCoException or UnknownSoCoException upon errors.
and then add a thorough explanation in the exceptions classes instead (which people will be able to read about on ReadTheDocs). That would save us a lot of repeated "code" and I think still properly provide the information that people need.
Just a few thought. Nice work and let me know what you think.
I've moved the exception classes to soco.exceptions in 4e8e761
I've shortened the text to
Raises SoCoException (or a subclass) upon errors.
which is a bit more generic (cd41bac).
So is there consensus to remove those return values?
I think the commits look good. Let's see where the other stand on the return values.
I've just removed the return True on success now ;)
@rahims, what do you think?
It would be great to get this committed. @rahims do you have any thoughts on the above?
On a related issues, maybe we should discuss what it takes to approve something for commit. I will open the discussion in a separate thread.
As per the new code acceptance criteria and @rahims comments on that, I think it should be safe to merge this. @stefankoegl will you do the honors?
raise exceptions instead of returning error info
mention raised exceptions in docstrings
move SoCoExceptions to soco.exceptions
don't return True on success
this is unnecessary as we're raising exceptions on error anyway
I've rebased my changes onto master and pushed them to the main repository. Thanks :)