Merge branch 'simple_put'

See pull-request #29

Conflicts:
	test_discid.py

discid/__init__.py

@@ -27,7 +27,7 @@
 and will raise :exc:`OSError` when libdiscid is not found.
 """
 
-from discid.disc import read, put, Disc, DiscError
+from discid.disc import read, put, Disc, DiscError, TOCError
 from discid.track import Track
 from discid.deprecated import DiscId
 import discid.libdiscid

discid/disc.py

@@ -53,23 +53,36 @@ def read(device=None, features=[]):
     disc.read(device, features)
     return disc
 
-def put(first, last, offsets):
-    """Creates a TOC based on the offsets given
+def put(first, last, disc_sectors, track_offsets):
+    """Creates a TOC based on the information given
     and returns a :class:`Disc` object.
 
-    Takes the *first* and *last* **audio** tracks as :obj:`int` and
-    *offsets* is supposed to be the same as :attr:`track_offsets`.
-    That is: ``offsets[0]`` are the total number of sectors
-    and the following are the offsets of each track.
+    Takes the `first` track and `last` **audio** track as :obj:`int`.
+    `disc_sectors` is the end of the last audio track,
+    normally the total sector count of the disc.
+    `track_offsets` is a list of all audio track offsets.
+
+    Depending on how you get the total sector count,
+    you might have to substract 11400 (2:32 min.) for discs with data tracks.
+
+    A :exc:`TOCError` exception is raised when illegal parameters
+    are provided.
+
+    .. seealso:: :musicbrainz:`Disc ID Calculation`
     """
     disc = Disc()
-    disc.put(first, last, offsets)
+    disc.put(first, last, disc_sectors, track_offsets)
     return disc
 
 
 class DiscError(IOError):
     """:func:`read` will raise this exception when an error occured.
-    An error string (:obj:`unicode`/:obj:`str <python:str>`) is provided.
+    """
+    pass
+
+class TOCError(Exception):
+    """:func:`put` will raise this exception when illegal paramaters
+    are provided.
     """
     pass
 
@@ -141,22 +154,26 @@ def read(self, device=None, features=[]):
 
     _LIB.discid_put.argtypes = (c_void_p, c_int, c_int, c_void_p)
     _LIB.discid_put.restype = c_int
-    # TODO: test if input is valid (int rather than string, ...)
-    def put(self, first, last, offsets):
-        """Creates a TOC based on the offsets given.
+    def put(self, first, last, disc_sectors, track_offsets):
+        """Creates a TOC based on the input given.
 
         The user is supposed to use :func:`discid.put`.
         """
+        # check for common usage errors
+        if len(track_offsets) != last - first + 1:
+            raise TOCError("Invalid number of track offsets")
+        elif False in [disc_sectors >= off for off in track_offsets]:
+            raise TOCError("Disc sector count too low")
+
         # only the "read" (= TOC) feature is supported by put
         self._requested_features = ["read"]
 
+        offsets = [disc_sectors] + track_offsets
         c_offsets = (c_int * len(offsets))(*tuple(offsets))
         result = _LIB.discid_put(self._handle, first, last, c_offsets) == 1
         self._success = result
         if not self._success:
-            # TODO: should that be the same Exception as for read()?
-            # should that be TOCError?
-            raise DiscError(self._get_error_msg())
+            raise TOCError(self._get_error_msg())
         return self._success
 
 

doc/discid.rst

@@ -10,13 +10,10 @@ At the module level there are these constants available:
 
 .. autodata:: LIBDISCID_VERSION_STRING
    :annotation:
-
 .. autodata:: DEFAULT_DEVICE
    :annotation:
-
 .. autodata:: FEATURES
    :annotation:
-
 .. autodata:: FEATURES_IMPLEMENTED
 
 Functions
@@ -26,7 +23,6 @@ These functions are used to create a :class:`Disc` object.
 .. autofunction:: read
 .. autofunction:: put
 
-
 Disc object
 -----------
 .. autoclass:: Disc
@@ -44,7 +40,6 @@ Disc object
    .. autoattribute:: mcn
    .. autoattribute:: tracks
 
-
 Track object
 ------------
 .. autoclass:: Track
@@ -63,3 +58,5 @@ The discid module includes a custom exception to handle specific problems:
 
 .. autoexception:: DiscError
    :show-inheritance:
+.. autoexception:: TOCError
+   :show-inheritance:

doc/usage.rst

@@ -48,8 +48,9 @@ An example for the TOC
 
  first = 1
  last = 15
- offsets = [258725] + [150, 17510, ..., 235590]
- disc = discid.put(first, last, offsets)
+ sectors = 258725
+ offsets = [150, 17510, ..., 235590]
+ disc = discid.put(first, last, sectors, offsets)
  print("id: %s" % disc.id)
  last_track = disc.tracks[disc.last_track_num - 1]
  print("last track length: %s seconds" % last_track.seconds)
@@ -60,8 +61,8 @@ An example for the TOC
    11400 (2:32 minutes) from your sector count.
    Make sure the last track length is correct!
 
-See also :musicbrainz:`Disc ID Calculation` for details
-on which numbers to choose.
+.. seealso:: :musicbrainz:`Disc ID Calculation` for details
+   on which numbers to choose.
 
 .. _fetching_metadata:
 

test_discid.py

@@ -12,7 +12,8 @@
             "name": "Guano Apes - Don't give Me Names, without last data track",
             "first": 1,
             "last" : 15,
-            "offsets": [258725, 150, 17510, 33275, 45910,
+            "sectors": 258725,
+            "offsets": [150, 17510, 33275, 45910,
                         57805, 78310, 94650,109580, 132010,
                         149160, 165115, 177710, 203325, 215555, 235590],
             "id": "TqvKjMu7dMliSfmVEBtrL7sBSno-",
@@ -71,23 +72,25 @@ def test_device_encoding(self):
         self.assertRaises(discid.DiscError, discid.read, devicebytes)
 
     def test_put_fail(self):
-        # it will only fail because first > last
-        first = 15
-        last = 1
-        offsets = [258725, 150, 17510, 33275, 45910] # also wrong
-        self.assertRaises(discid.DiscError, discid.put, first, last, offsets)
+        # not enough offsets
+        self.assertRaises(discid.TOCError, discid.put, 1, 2, 150, [150])
+        # too many offsets
+        self.assertRaises(discid.TOCError,
+                          discid.put, 1, 2, 1000, [150, 500, 750])
+        # total sectors / offset mismatch
+        self.assertRaises(discid.TOCError, discid.put, 1, 2, 150, [150, 500])
 
     def test_put_success(self):
         test_disc = test_discs[0]
         disc = discid.put(test_disc["first"], test_disc["last"],
-                          test_disc["offsets"])
+                          test_disc["sectors"], test_disc["offsets"])
         self.assertEqual(disc.id, test_disc["id"])
         self.assertEqual(disc.freedb_id, test_disc["freedb"])
         self.assertEqual(disc.first_track_num, test_disc["first"])
         self.assertEqual(disc.last_track_num, test_disc["last"])
-        self.assertEqual(disc.sectors, test_disc["offsets"][0])
+        self.assertEqual(disc.sectors, test_disc["sectors"])
         track_offsets = [track.offset for track in disc.tracks]
-        self.assertEqual(track_offsets, test_disc["offsets"][1:])
+        self.assertEqual(track_offsets, test_disc["offsets"])
         self.assertEqual(disc.sectors,
                          disc.tracks[-1].offset + disc.tracks[-1].sectors)
         self.assertEqual(disc.seconds,
@@ -97,7 +100,6 @@ def test_put_success(self):
                              track.sectors // discid.util.SECTORS_PER_SECOND)
 
 
-
 class TestClass(unittest.TestCase):
 
     def setUp(self):
@@ -163,11 +165,11 @@ def test_read_simple(self):
         submission_url = disc.submission_url
         first = disc.first_track_num
         last = disc.last_track_num
-        track_offsets = [track.offset for track in disc.tracks]
-        offsets = [disc.sectors] + track_offsets
+        sectors = disc.sectors
         track_sectors = [track.sectors for track in disc.tracks]
+        track_offsets = [track.offset for track in disc.tracks]
 
-        disc = discid.put(first, last, offsets)
+        disc = discid.put(first, last, sectors, track_offsets)
         self.assertEqual(disc.id, disc_id, "different id after put")
         self.assertEqual(disc.freedb_id, freedb_id,
                          "different freedb id after put")
@@ -177,7 +179,7 @@ def test_read_simple(self):
                          "different first track after put")
         self.assertEqual(disc.last_track_num, last,
                          "different last track after put")
-        self.assertEqual(disc.sectors, offsets[0],
+        self.assertEqual(disc.sectors, sectors,
                          "different sector count after put")
         new_offsets = [track.offset for track in disc.tracks]
         self.assertEqual(new_offsets, track_offsets,
@@ -207,7 +209,7 @@ def test_read_put(self):
         disc = discid.read(features=["mcn", "isrc"]) # read from default drive
         test_disc = test_discs[0]
         disc = discid.put(test_disc["first"], test_disc["last"],
-                          test_disc["offsets"])
+                          test_disc["sectors"], test_disc["offsets"])
         self.assertTrue(disc.mcn is None)
         for track in disc.tracks:
             self.assertTrue(track.isrc is None)