From ddddbbb9197257d06b4eb4c3b2d3cf7e59c8b6b4 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Fri, 21 Mar 2014 17:51:50 -0700
Subject: [PATCH] some more thorough documentation for #614

---
 beets/mediafile.py     | 27 ++++++++++++++++++++-------
 test/test_mediafile.py |  6 +++---
 2 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/beets/mediafile.py b/beets/mediafile.py
index 9213a5c42..81036ffa4 100644
--- a/beets/mediafile.py
+++ b/beets/mediafile.py
@@ -1020,20 +1020,33 @@ class DateField(MediaField):
         self._set_date_tuple(mediafile, date.year, date.month, date.day)
 
     def _get_date_tuple(self, mediafile):
-        datestring = MediaField.__get__(self, mediafile, None)
+        """Get a 3-item sequence representing the date consisting of a
+        year, month, and day number. Each number is either an integer or
+        None.
+        """
+        # Get the underlying data and split on hyphens.
+        datestring = super(DateField, self).__get__(mediafile, None)
         datestring = re.sub(r'[Tt ].*$', '', unicode(datestring))
         items = unicode(datestring).split('-')
-        # A date with more than 3 components is not a date we understand.  In
-        # that case, act like we saw no date components.
-        if len(items) > 3:
-            items = []
-        items = items + [None] * (3 - len(items))
+
+        # Ensure that we have exactly 3 components, possibly by
+        # truncating or padding.
+        items = items[:3]
+        if len(items) < 3:
+            items += [None] * (3 - len(items))
+
+        # Use year field if year is missing.
         if not items[0] and hasattr(self, '_year_field'):
-            # Fallback to addition year field
             items[0] = self._year_field.__get__(mediafile)
+
+        # Convert each component to an integer if possible.
         return [_safe_cast(int, item) for item in items]
 
     def _set_date_tuple(self, mediafile, year, month=None, day=None):
+        """Set the value of the field given a year, month, and day
+        number. Each number can be an integer or None to indicate an
+        unset component.
+        """
         date = [year or 0]
         if month:
             date.append(month)
diff --git a/test/test_mediafile.py b/test/test_mediafile.py
index 92035825b..94c4a0ac0 100644
--- a/test/test_mediafile.py
+++ b/test/test_mediafile.py
@@ -198,7 +198,7 @@ class LazySaveTestMixin(object):
         self.assertNotEqual(os.stat(mediafile.path).st_mtime, mtime)
 
     def _set_past_mtime(self, path):
-        mtime = round(time.time()-10000)
+        mtime = round(time.time() - 10000)
         os.utime(path, (mtime, mtime))
         return mtime
 
@@ -333,7 +333,8 @@ class ReadWriteTestBase(ArtTestMixin, GenreListTestMixin):
         mediafile = self._mediafile_fixture('full')
         for key, value in self.audio_properties.items():
             if isinstance(value, float):
-                self.assertAlmostEqual(getattr(mediafile, key), value, delta=0.1)
+                self.assertAlmostEqual(getattr(mediafile, key), value,
+                                       delta=0.1)
             else:
                 self.assertEqual(getattr(mediafile, key), value)
 
@@ -474,7 +475,6 @@ class ReadWriteTestBase(ArtTestMixin, GenreListTestMixin):
         self.assertEqual(mediafile.date, datetime.date.min)
 
     def assertTags(self, mediafile, tags):
-        __unittest = True
         errors = []
         for key, value in tags.items():
             try: