srt: neater docstrings, some cleanup

ox/srt.py

@@ -51,11 +51,12 @@ def _detect_encoding(fp):
 
 
 def load(filename, offset=0):
-    '''
+    '''Parses an srt file
-        filename path to an srt file
-        offset in seconds shift all in/out points by offset
 
-        returns list with objects that have in,out,value and id
+    filename: path to an srt file
+    offset (float, seconds): shift all in/out points by offset
+
+    Returns list with dicts that have in, out, value and id
     '''
     srt = []
 
@@ -87,20 +88,30 @@ def load(filename, offset=0):
         i += 1
     return srt
 
+
+def _srt_timecode(t):
+    return ox.format_duration(t * 1000, years=False).replace('.', ',')
+
+
 def encode(data):
-    '''
+    """Encodes subtitles into SRT format
-        encodes list of objects with in,out,value into srt
+
-        result is utf-8 encoded bytestring
+    data: list of dicts with 'in', 'out': float and 'value': unicode
-    '''
+
+    Returns: a UTF-8-encoded bytestring
+
+    >>> encode([{'in': 1.25, 'out': 60 * 60 + 1, 'value': u'touch\\u00E9'}])
+    '\\xef\\xbb\\xbf1\\r\\n00:00:01,250 --> 01:00:01,000\\r\\ntouch\\xc3\\xa9\\r\\n\\r\\n'
+    """
+
     srt = u''
-    i = 1
+
-    for s in data:
+    for i, s in enumerate(data, 1):
         srt += '%d\r\n%s --> %s\r\n%s\r\n\r\n' % (
             i,
-            ox.format_duration(s['in']*1000, years=False).replace('.', ','),
+            _srt_timecode(s['in']),
-            ox.format_duration(s['out']*1000, years=False).replace('.', ','),
+            _srt_timecode(s['out']),
             s['value'].replace('\n', '\r\n').strip()
         )
-        i += 1
-    return codecs.BOM_UTF8 + srt.encode('utf-8')
 
+    return codecs.BOM_UTF8 + srt.encode('utf-8')