SoCo/SoCo — pull request #61 by KennethNielsen (2013-12-16 23:04:44+00:00)
Title: Music library data structures

So I finally finished the first batch of the changes to implement classes for data structures. These changes implement data structure for all music library items. The means that:

* get_music_library_information and all the derived methods from that now return music library object e.g. MLTrack etc.
* add_to_queue now no longer accepts URI's as arguments but only instances of MusicLibraryItems. If desired, the old method can be re-added as a legacy function, but I think this is the way to go and it is still possible to make and data structure from a URI and pass that to the method

I have also added some documentation that explains the inheritance for these objects.

All of the data structures can be compare with =, they have usable str representations and are hashable, which means that they can be used as dict keys.

As an experiment I have fully Sphinx'ified all the doc strings. This means that they are less readable from a python interpreter, but much more beautiful and usable on ReadTheDocs.

I have **not yet** modified the get_queue method, since the queue can contain music service tracks and the data structures for those have not yet been implemented. That is next on the list. but I wanted to get some feedback on this first.

One point in specific that I am looking for feedback on is whether or override get_didl_metadata in each of the music library item classes in stead of just lettings the one in the super class know what to do for the different classes. Not doing it could shave around 150 lines of code of the module, but at the expense of not having specific doc strings for each class and vice versa. I guess you could argue both ways I and was in doubt, but leaned towards actually overriding them, which is why that is what it is in the commit, but I am open to opinions.

I have not implemented tests yet, again because I wanted some feedback first, but that will also follow if it is commited. Due to all the resent changes, I had to manually rebase the commit on head, which ***might*** have introduced some errors, so I promise to implement tests soon :D

Here are some usage examples::

```python
def example_data(soc):
for search in ['folders', 'artists', 'album_artists', 'albums', 'genres',
'composers', 'tracks', 'share', 'playlists']:
items = soc.get_music_library_information(search, 0, 100)
item = items['item_list'][0]
print item
print '{0: <16}{1}'.format(search, item.title.encode('utf-8'))

def example_add(soc):
for search in ['artists', 'album_artists', 'albums', 'genres',
'composers', 'tracks', 'playlists']:
items = soc.get_music_library_information(search, 0, 1)
item = items['item_list'][0]
print item
print 'Press enter to add'
raw_input()
soc.add_to_queue(item)

soc = soco.SoCo('192.168.0.10')
items = soc.get_albums()
print items['item_list'][0]
example_add(soc)
example_data(soc)
```

(careful, the example_add will add stuff to your queue)

Let me know what you think.

Regards Kenneth