Added type annotations and doc fixes

docs/source/conf.py

@@ -15,18 +15,19 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../..'))
-print(sys.path)
+
+import pycmx
 
 # -- Project information -----------------------------------------------------
 
 project = u'pycmx'
-copyright = u'2022, Jamie Hardt'
+copyright = u'(c) 2023, Jamie Hardt'
 author = u'Jamie Hardt'
 
 # The short X.Y version
-version = u''
+version = pycmx.__version__
 # The full version, including alpha/beta/rc tags
-release = u''
+release = pycmx.__version__
 
 
 # -- General configuration ---------------------------------------------------

pycmx/edit.py

@@ -3,7 +3,9 @@
 
 from .transition import Transition
 from .channel_map import ChannelMap
-from .parse_cmx_statements import StmtEffectsName
+# from .parse_cmx_statements import StmtEffectsName
+
+from typing import Optional
 
 class Edit:
     """
@@ -18,7 +20,7 @@ class Edit:
         self.trans_name_statement = trans_name_statement 
 
     @property
-    def line_number(self):
+    def line_number(self) -> int:
         """
         Get the line number for the "standard form" statement associated with
         this edit. Line numbers a zero-indexed, such that the 
@@ -27,7 +29,7 @@ class Edit:
         return self.edit_statement.line_number
 
     @property
-    def channels(self):
+    def channels(self) -> ChannelMap:
         """
         Get the :obj:`ChannelMap` object associated with this Edit.
         """
@@ -38,7 +40,7 @@ class Edit:
         return cm
 
     @property
-    def transition(self):
+    def transition(self) -> Transition:
         """
         Get the :obj:`Transition` object associated with this edit.
         """
@@ -48,14 +50,14 @@ class Edit:
             return Transition(self.edit_statement.trans, self.edit_statement.trans_op, None)
     
     @property
-    def source_in(self):
+    def source_in(self) -> str:
         """
         Get the source in timecode.
         """
         return self.edit_statement.source_in
 
     @property
-    def source_out(self):
+    def source_out(self) -> str:
         """
         Get the source out timecode.
         """
@@ -63,7 +65,7 @@ class Edit:
         return self.edit_statement.source_out
 
     @property
-    def record_in(self):
+    def record_in(self) -> str:
         """
         Get the record in timecode.
         """
@@ -71,7 +73,7 @@ class Edit:
         return self.edit_statement.record_in
 
     @property
-    def record_out(self):
+    def record_out(self) -> str:
         """
         Get the record out timecode.
         """
@@ -79,7 +81,7 @@ class Edit:
         return self.edit_statement.record_out
 
     @property
-    def source(self):
+    def source(self) -> str:
         """
         Get the source column. This is the 8, 32 or 128-character string on the
         event record line, this usually references the tape name of the source.
@@ -87,21 +89,21 @@ class Edit:
         return self.edit_statement.source
 
     @property
-    def black(self):
+    def black(self) -> bool:
         """
         Black video or silence should be used as the source for this event.
         """
         return self.source == "BL"
 
     @property
-    def aux_source(self):
+    def aux_source(self) -> bool:
         """
         An auxiliary source is the source of this event.
         """
         return self.source == "AX"
 
     @property
-    def source_file(self):
+    def source_file(self) -> Optional[str]:
         """
         Get the source file, as attested by a "* SOURCE FILE" remark on the
         EDL. This will return None if the information is not present.
@@ -112,7 +114,7 @@ class Edit:
             return self.source_file_statement.filename
 
     @property
-    def clip_name(self):
+    def clip_name(self) -> Optional[str]:
         """
         Get the clip name, as attested by a "* FROM CLIP NAME" or "* TO CLIP 
         NAME" remark on the EDL. This will return None if the information is

pycmx/edit_list.py

@@ -5,21 +5,21 @@ from .parse_cmx_statements import (StmtUnrecognized, StmtFCM, StmtEvent, StmtSou
 from .event import Event
 from .channel_map import ChannelMap
 
+from typing import Generator
+
 class EditList:
     """
-    Represents an entire edit decision list as returned by `parse_cmx3600()`.
+    Represents an entire edit decision list as returned by :func:`~pycmx.parse_cmx3600()`.
-    
     """
     def __init__(self, statements):
         self.title_statement = statements[0]
         self.event_statements = statements[1:]
 
-    
     @property
-    def format(self):
+    def format(self) -> str:
         """
-        The detected format of the EDL. Possible values are: `3600`,`File32`,
+        The detected format of the EDL. Possible values are: "3600", "File32",
-        `File128`, and `unknown`
+        "File128", and "unknown".
         """
         first_event = next( (s for s in self.event_statements if type(s) is StmtEvent), None)
 
@@ -37,7 +37,7 @@ class EditList:
         
 
     @property
-    def channels(self):
+    def channels(self) -> ChannelMap:
         """
         Return the union of every channel channel.
         """
@@ -51,7 +51,7 @@ class EditList:
         
 
     @property
-    def title(self):
+    def title(self) -> str:
         """
         The title of this edit list.
         """
@@ -59,7 +59,7 @@ class EditList:
 
     
     @property
-    def unrecognized_statements(self):
+    def unrecognized_statements(self) -> Generator[StmtUnrecognized, None, None]:
         """
         A generator for all the unrecognized statements in the list.
         """
@@ -69,7 +69,7 @@ class EditList:
         
 
     @property
-    def events(self):
+    def events(self) -> Generator[Event, None, None]:
         'A generator for all the events in the edit list'
         is_drop = None
         current_event_num = None
@@ -97,7 +97,7 @@ class EditList:
         yield Event(statements=event_statements)
 
     @property
-    def sources(self):
+    def sources(self) -> Generator[StmtSourceUMID, None, None]:
         """
         A generator for all of the sources in the list
         """

pycmx/event.py

@@ -1,26 +1,28 @@
 # pycmx
-# (c) 2018 Jamie Hardt
+# (c) 2023 Jamie Hardt
 
 from .parse_cmx_statements import (StmtEvent, StmtClipName, StmtSourceFile, StmtAudioExt, StmtUnrecognized, StmtEffectsName)
 from .edit import Edit
 
+from typing import List, Generator
+
 class Event:
     """
-    Represents a collection of :class:`Edit`s, all with the same event number.
+    Represents a collection of :class:`~pycmx.edit.Edit` s, all with the same event number.
     """
 
     def __init__(self, statements):
         self.statements = statements
     
     @property
-    def number(self):
+    def number(self) -> int:
         """
         Return the event number.
         """
         return int(self._edit_statements()[0].event)
 
     @property
-    def edits(self):
+    def edits(self) -> List[Edit]:
         """
         Returns the edits. Most events will have a single edit, a single event
         will have multiple edits when a dissolve, wipe or key transition needs
@@ -63,11 +65,10 @@ class Event:
         except IndexError:
             the_zip.append([None] * len(edits_audio) )
 
-
         return [ Edit(e1[0],e1[1],n1,s1,u1) for (e1,n1,s1,u1) in zip(*the_zip) ]
             
     @property
-    def unrecognized_statements(self):
+    def unrecognized_statements(self) -> Generator[StmtUnrecognized, None, None]:
         """
         A generator for all the unrecognized statements in the event.
         """