Rework examples/demos

[alastair]

Move examples from a single file to a series of demos that use all the features that are available

Features that should be demonstrated:

• [x] Get
• [x] Includes
• [x] Release status / type
• [ ] Browse
• [ ] Paging
• [ ] Submission
• [x] Search
• [x] Advanced search
• [x] Setting passwords
• [x] Collections

[JonnyJD]

We should have an example directory.

We should not only demonstrate the use of our functions, but also how to get to the data. It is not obvious right now what you get after using these functions. We also need some better overall documentation (epydoc, sphinx or something else). The first problem I had using the lib is to find out how to use it and it wasn't at all obvious that you get dicts instead of classes (like in Pymb2).

Something like this is desperately needed in the examples:

def print_releases(result):
    for release in result["release-list"]:
        artistcredit = release["artist-credit"][0]["artist"]
        artist = artistcredit["name"][:13]
        title = release["title"][:35]
        print "\tartist: %s \t release: %s" % (artist, title)

I do plan to move some stuff from https://gist.github.com/2158321 into proper examples and tests, but what's there now too much clutter for simple examples. Like I said in the closed pull request: The main purpose of the current gist ist to demonstrate problems and to make sure that my commits work as expected.

Before we start adding wild examples we should think about a structure. One file for every feature would be overkill.

[JonnyJD]

I would propose several files with a specific use case.

@sampsyo is already using this lib, so he might be able to put together a quick use case.

My use case would be to get a release by discID, get the recordings/tracks, and display some information about it. (finally I would get and submit ISRCs with that). @mineo might already have such a script, I don't know.

What's missing is libdiscid support, as far as I can see. I should open a report.

By the way: Is the API actually decided yet? For example, I think musicbrainzngs.musicbrainz might not be a good module name/path. Maybe musicbrainzngs.mb would be enough. Is there a decision if we can use the name (python-)musicbrainz3? (doesn't keep us from starting examples, though)

[alastair]

I have init.py set up so that you can just "import musicbrainzngs". This is my preferred usage.

I agree with the examples directory with how to use responses.

[sampsyo]

There's one to get us started. It's just a simple use of search_releases with keyword arguments and some light usage of the result dictionary.

[sampsyo]

I've added a second example, collection.py, which demonstrates the functions involving collections (get collections, list releases in a collection, add to collection, remove from collection). The real motivation here was to test some bug fixes, but I tried to write it up as a useful example as well. https://github.com/alastair/python-musicbrainz-ngs/blob/master/examples/collection.py

[alastair]

We need to make sure we include an example like fc2d588b7f3ba647459fc0ced5eb0749e7268a68 (adding includes to a get query)

[JonnyJD]

Closing this.

We still don't have examples using browsing/paging and submission in the examples directory. However we have documented this directly in the documentation.