rbrainz 0.4.2 → 0.5.0

data/CHANGES

@@ -1,5 +1,17 @@
 = Changelog
 
+== 0.5.0 (2009-06-14)
+* NEW: Support for release groups
+* NEW: Support for ISRCs, including ISRC submission
+* NEW: Support for ratings, including rating submission
+* NEW: Common exception class for all web service errors
+* NEW: Updated language list
+* NEW: Allow exclusion of CD stubs in ReleaseFilter
+* BUG: Added source file encodings for Ruby 1.9 compatibillity
+* BUG: Fixed Release#single_artist_release?
+* BUG: Added all missing include options for artists
+* BUG: Always raise a ConnectionError for unknown errors in the web service
+
 == 0.4.2 (2008-09-04)
 * BUG: Fixed proxy authentication
 * BUG: Fixed raising of ResponseError in Query#get_user_by_name
@@ -65,4 +77,4 @@
 == 0.1.0 (2007-05-23)
 * Initial release
 
-$Id: CHANGES 219 2008-09-04 18:14:48Z phw $
+$Id: CHANGES 280 2009-06-14 20:58:18Z phw $

data/LICENSE

@@ -1,4 +1,4 @@
-RBrainz is Copyright (c) 2007 Philipp Wolfer and Nigel Graham.
+RBrainz is Copyright (c) 2007-2009 Philipp Wolfer and 2007 Nigel Graham.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions

data/README

@@ -7,6 +7,6 @@ To generate the complete RBrainz documentation run
  
 The documentation will be stored in doc/api.
 
-RBrainz is Copyright (c) 2007 Philipp Wolfer and Nigel Graham.
+RBrainz is Copyright (c) 2007-2009 Philipp Wolfer and 2007 Nigel Graham.
 It is free softare distributed under a BSD style license. See
-LICENSE for details.
+LICENSE for details.

data/Rakefile

@@ -1,4 +1,5 @@
-# $Id: Rakefile 226 2008-09-04 19:51:48Z phw $
+# -*- coding: utf-8 -*-
+# $Id: Rakefile 274 2009-05-24 22:44:42Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -25,7 +26,6 @@ PKG_FILES = FileList[
   "lib/**/*.rb",
   "test/**/*.rb",
   "test/test-data/**/*",
-  "debian/*"
 ]
 PKG_EXTRA_RDOC_FILES = ['doc/README.rdoc', 'LICENSE', 'TODO', 'CHANGES']
 

data/TODO

@@ -1,12 +1,19 @@
 = TODO
 
+== 0.5 release
+* Add i18n (nigel)
+* Test all examples
+
 == Short term tasks
+* Add mass submission API for tags and ratings.
+* CD stub submission
+* Support music collection WS.
 * Improve API documentation.
 
 == Longer term tasks
 * Implement a command line tool (+mbquery+) for querying the MusicBrainz
-  database which will serve as a usefull example for RBrainz.
+  database which will serve as a useful example for RBrainz.
 * Support for common extensions (this could be implemented by adding
   additional extension libraries which extend the existing classes).
   
-$Id: TODO 129 2007-07-12 17:52:17Z phw $
+$Id: TODO 277 2009-05-25 19:33:26Z phw $

data/doc/README.rdoc

@@ -9,8 +9,8 @@ used to PythonMusicBrainz2 should already know most of RBrainz' interface.
 However, RBrainz differs from PythonMusicBrainz2 wherever it makes the
 library more Ruby like or easier to use.
 
-RBrainz supports the MusicBrainz XML Metadata Version 1.2, including support
-for labels and extended release events.
+RBrainz supports the MusicBrainz XML Metadata Version 1.4, including support
+for labels, extended release events, release groups and ratings.
 
 == Installation
 === Installing with RubyGems
@@ -92,12 +92,12 @@ If you find bugs or if you have any feature requests please use the
 RBrainz bug tracker[http://rubyforge.org/tracker/?group_id=3677]. 
 
 == Authors
-* Nigel Graham
 * Philipp Wolfer
+* Nigel Graham
 
 == License
-RBrainz is Copyright (c) 2007 Philipp Wolfer and Nigel Graham.
+RBrainz is Copyright (c) 2007-2009 Philipp Wolfer and 2007 Nigel Graham.
 It is free softare distributed under a BSD style license. See
 LICENSE[link:files/LICENSE.html] for details.
 
-$Id: README.rdoc 191 2007-12-04 13:30:26Z phw $
+$Id: README.rdoc 252 2009-05-13 19:21:28Z phw $

data/examples/getartist.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which queries the database for an
 # artist and displays the artist's data.
 # 
-# $Id: getartist.rb 162 2007-07-29 17:44:11Z phw $
+# $Id: getartist.rb 273 2009-05-24 22:29:04Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -53,4 +54,4 @@ Begin date    : #{artist.begin_date}
 End date      : #{artist.end_date}
 Aliases       : #{artist.aliases.to_a.join('; ')}
 Releases      : #{artist.releases.map{|r| r.title}.uniq.join("\r\n                ")}
-EOF
+EOF

data/examples/getlabel.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which queries the database for an
 # label and displays the label's data.
 # 
-# $Id: getlabel.rb 160 2007-07-27 13:18:04Z phw $
+# $Id: getlabel.rb 254 2009-05-13 20:04:36Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -50,4 +51,4 @@ Type          : #{label.type}
 Begin date    : #{label.begin_date}
 End date      : #{label.end_date}
 Aliases       : #{label.aliases.to_a.join('; ')}
-EOF
+EOF

data/examples/getrelease.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which queries the database for an
 # release and displays the release's data.
 # 
-# $Id: getrelease.rb 190 2007-12-04 12:51:17Z phw $
+# $Id: getrelease.rb 278 2009-06-07 21:30:51Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -28,6 +29,7 @@ mbid = Model::MBID.parse(id, :release)
 release_includes = Webservice::ReleaseIncludes.new(
   :artist => true,
   :tracks => true,
+  :release_groups => true,
   :release_events => true
 )
 
@@ -47,10 +49,11 @@ print <<EOF
 ID            : #{release.id.uuid}
 Title         : #{release.title}
 Artist        : #{release.artist.unique_name}
+Release Group : #{release.release_group.title}
 Tracks        : #{release.tracks.to_a.join("\r\n                ")}
 Release Events:
 EOF
 
 release.release_events.each do |event|
   puts "#{event.date} #{Utils.get_country_name(event.country)}"
-end
+end

data/examples/getreleasegroup.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+#
+# Example script which queries the database for a
+# release group and displays the release group's data.
+# 
+# $Id: getreleasegroup.rb 276 2009-05-24 23:37:18Z phw $
+
+# Just make sure we can run this example from the command
+# line even if RBrainz is not yet installed properly.
+$: << 'lib/' << '../lib/'
+
+# Load RBrainz and include the MusicBrainz namespace.
+require 'rbrainz'
+include MusicBrainz
+
+# The release's MusicBrainz ID.
+# Either read it from the command line as the first
+# parameter or use a default one for demonstration.
+id = $*[0] ? $*[0] : 'a07cbaff-aa79-35a9-9932-af7335f306eb'
+
+# Generate a new release MBID object from the ID:
+mbid = Model::MBID.parse(id, :release_group)
+
+# Define what information about the release group
+# should be included in the result.
+# In this case the release group's artist and and
+# releases will be fetched as well.
+release_group_includes = Webservice::ReleaseGroupIncludes.new(
+  :artist => true,
+  :releases => true
+)
+
+# Create a new Query object which will provide
+# us an interface to the MusicBrainz web service.
+query = Webservice::Query.new
+
+# Now query the MusicBrainz database for the release
+# group with the MBID defined above.
+# We could as well use the ID string directly instead
+# of the MBID object.
+release_group = query.get_release_group_by_id(mbid, release_group_includes)
+
+# Display the fetched release group data together with all
+# unique release titles.
+print <<EOF
+ID            : #{release_group.id.uuid}
+Title         : #{release_group.title}
+Types         : #{release_group.types.to_a.join(", ")}
+Artist        : #{release_group.artist.unique_name}
+Releases      : #{release_group.releases.to_a.join("\r\n                ")}
+EOF
+

data/examples/gettrack.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which queries the database for an
 # track and displays the track's data.
 # 
-# $Id: gettrack.rb 160 2007-07-27 13:18:04Z phw $
+# $Id: gettrack.rb 254 2009-05-13 20:04:36Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -48,4 +49,4 @@ Title         : #{track.title}
 Duration      : #{track.duration/1000} seconds
 Artist        : #{track.artist.unique_name}
 Release       : #{track.releases.to_a.join("\r\n                ")}
-EOF
+EOF

data/examples/getuser.rb

@@ -1,8 +1,9 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which queries the database for a user.
 # 
-# $Id: getuser.rb 183 2007-10-16 22:13:33Z phw $
+# $Id: getuser.rb 273 2009-05-24 22:29:04Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.

data/examples/rate.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+#
+# Example script showing the use of ratings with RBrainz.
+# It asks the user for his username and password and a MBID and queries the
+# MusicBrainz server for the rating, the user has applied to the entitity with
+# the given MBID. Afterwards the user can submit a new rating.
+# 
+# $Id: rate.rb 273 2009-05-24 22:29:04Z phw $
+
+# Just make sure we can run this example from the command
+# line even if RBrainz is not yet installed properly.
+$: << 'lib/' << '../lib/'
+
+# Load RBrainz and include the MusicBrainz namespace.
+require 'rbrainz'
+include MusicBrainz
+
+# Get the username and password
+print 'Username: ' unless ARGV[0]
+username = ARGV[0] ? ARGV[0] : STDIN.gets.strip
+print 'Password: ' unless ARGV[1]
+password = ARGV[1] ? ARGV[1] : STDIN.gets.strip
+
+# Ask for a MBID to tag. The MBID must be a complete MusicBrainz identifier,
+# e.g. http://musicbrainz.org/release/6785cad0-159c-40ec-9ee4-30d8745dd7f9
+print 'Enter a MBID: '
+mbid = Model::MBID.new(STDIN.gets.strip)
+
+# Set the authentication for the webservice.
+ws = Webservice::Webservice.new(:username=>username, :password=>password) 
+
+# Create a new Query object which will provide
+# us an interface to the MusicBrainz web service.
+query = Webservice::Query.new(ws, :client_id => 'RBrainz test ' + RBRAINZ_VERSION)
+
+# Read and print the current rating for the given MBID.
+rating = query.get_user_rating(mbid)
+print "Current rating: #{rating.to_s}"
+
+# Ask the user for a new rating and submit it.
+print 'Enter new rating: '
+new_rating = STDIN.gets.strip
+query.submit_user_rating(mbid, new_rating.to_i)

data/examples/searchartists.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which searches the database for
 # artists and displays the artist's data.
 # 
-# $Id: searchartists.rb 145 2007-07-19 13:11:44Z phw $
+# $Id: searchartists.rb 273 2009-05-24 22:29:04Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -32,4 +33,4 @@ artists = query.get_artists(artist_filter)
 # indicates how good the artist matches the search parameters.
 artists.each do |entry|
   print "%s (%i%%)\r\n" % [entry.entity.unique_name, entry.score]
-end
+end

data/examples/searchcdstubs.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+#
+# Example script which searches the database for
+# releases by disc ID, including CD stubs.
+#
+# For more information about CD stubs see http://wiki.musicbrainz.org/CDStub
+#
+# $Id: searchcdstubs.rb 273 2009-05-24 22:29:04Z phw $
+
+# Just make sure we can run this example from the command
+# line even if RBrainz is not yet installed properly.
+$: << 'lib/' << '../lib/'
+
+# Load RBrainz and include the MusicBrainz namespace.
+require 'rbrainz'
+include MusicBrainz
+
+# Define the search parameters: Search for releases with the given disc ID
+# (which is a special disc ID for DVD releases and only available as a CD stub),
+# make sure to include CD stubs and return a maximum of 10 releases.
+release_filter = Webservice::ReleaseFilter.new(
+  :discid => 'flplyXqMOiodZEDJeDw5Ci6OD_g-',
+  :cdstubs => true,
+  :limit => 10
+)
+
+# Create a new Query object which will provide
+# us an interface to the MusicBrainz web service.
+query = Webservice::Query.new
+
+# Now query the MusicBrainz database for releases
+# with the search parameters defined above.
+releases = query.get_releases(release_filter)
+
+# Display the fetched release titles and their tracks
+releases.each do |entry|
+  release = entry.entity
+  puts "Title : #{release.title}"
+  puts "Tracks: #{release.tracks.to_a.join("\r\n        ")}"
+end

data/examples/searchlabels.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which searches the database for
 # labels and displays the label's data.
 # 
-# $Id: searchlabels.rb 160 2007-07-27 13:18:04Z phw $
+# $Id: searchlabels.rb 254 2009-05-13 20:04:36Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -32,4 +33,4 @@ labels = query.get_labels(label_filter)
 # indicates how good the label matches the search parameters.
 labels.each do |entry|
   print "%s (%i%%)\r\n" % [entry.entity.unique_name, entry.score]
-end
+end

data/examples/searchreleasegroups.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+#
+# Example script which searches the database for
+# release groups and displays the release group data.
+# 
+# $Id: searchreleasegroups.rb 273 2009-05-24 22:29:04Z phw $
+
+# Just make sure we can run this example from the command
+# line even if RBrainz is not yet installed properly.
+$: << 'lib/' << '../lib/'
+
+# Load RBrainz and include the MusicBrainz namespace.
+require 'rbrainz'
+include MusicBrainz
+
+# Define the search parameters: Search for release groups from the
+# band "Paradise Lost" and return a maximum of 10 release groups.
+release_group_filter = Webservice::ReleaseGroupFilter.new(
+  :artist => 'Paradise Lost',
+  :limit => 10
+)
+
+# Create a new Query object which will provide
+# us an interface to the MusicBrainz web service.
+query = Webservice::Query.new
+
+# Now query the MusicBrainz database for release groups
+# with the search parameters defined above.
+release_groups = query.get_release_groups(release_group_filter)
+
+# Display the fetched release group titles and the score, which
+# indicates how good the release matches the search parameters.
+release_groups.each do |entry|
+  print "%s (%i%%)\r\n" % [entry.entity.title, entry.score]
+end

data/examples/searchreleases.rb

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
 #
 # Example script which searches the database for
 # releases and displays the release data.
 # 
-# $Id: searchreleases.rb 183 2007-10-16 22:13:33Z phw $
+# $Id: searchreleases.rb 260 2009-05-17 19:00:53Z phw $
 
 # Just make sure we can run this example from the command
 # line even if RBrainz is not yet installed properly.
@@ -13,8 +14,9 @@ $: << 'lib/' << '../lib/'
 require 'rbrainz'
 include MusicBrainz
 
-# Define the search parameters: Search for releases with the
-# title "Paradise Lost" and return a maximum of 10 releases.
+# Define the search parameters: Search for releases for the band
+# "Paradise Lost" (which has the MusicBrainz ID 10bf95b6-30e3-44f1-817f-45762cdc0de0)
+# and return a maximum of 10 releases.
 release_filter = Webservice::ReleaseFilter.new(
   :artistid => '10bf95b6-30e3-44f1-817f-45762cdc0de0',
   :limit => 10
@@ -33,4 +35,4 @@ releases = query.get_releases(release_filter)
 releases.each do |entry|
   print "%s: %s (%i%%)\r\n" % [entry.entity.earliest_release_date,
                                entry.entity.title, entry.score]
-end
+end