[pitivi] Formatter: Write out design specifications in blank classes with documentation.

[Edward Hervey <edwardrv src gnome org>]

commit e5e6d9cb5eed6d43fe19b98f83d36529da486c79
Author: Edward Hervey <bilboed bilboed com>
Date:   Wed Jan 7 18:55:49 2009 +0100

    Formatter: Write out design specifications in blank classes with documentation.
---
 pitivi/formatters/__init__.py |   25 ++++++++++++
 pitivi/formatters/base.py     |   86 +++++++++++++++++++++++++++++++++++++++++
 pitivi/formatters/format.py   |   73 ++++++++++++++++++++++++++++++++++
 3 files changed, 184 insertions(+), 0 deletions(-)

diff --git a/pitivi/formatters/__init__.py b/pitivi/formatters/__init__.py
new file mode 100644
index 0000000..f902b96
--- /dev/null
+++ b/pitivi/formatters/__init__.py
@@ -0,0 +1,25 @@
+# PiTiVi , Non-linear video editor
+#
+#       pitivi.formatters
+#
+# Copyright (c) 2009, Edward Hervey <bilboed bilboed com>
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+"""
+Project store/load support
+"""
+
diff --git a/pitivi/formatters/base.py b/pitivi/formatters/base.py
new file mode 100644
index 0000000..f938d73
--- /dev/null
+++ b/pitivi/formatters/base.py
@@ -0,0 +1,86 @@
+# PiTiVi , Non-linear video editor
+#
+#       formatter.base
+#
+# Copyright (c) 2009, Edward Hervey <bilboed bilboed com>
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+"""
+Base Formatter classes
+"""
+
+from pitivi.project import Project
+
+class FormatterError(Exception):
+    pass
+
+class FormatterLoadError(FormatterError):
+    pass
+
+class FormatterSaveError(FormatterError):
+    pass
+
+# FIXME : How do we handle interaction with the UI ??
+# Do we blindly load everything and let the UI figure out what's missing from
+# the loaded project ?
+
+class Formatter(object):
+    """
+    Provides convenience methods for storing and loading
+    Project files.
+    """
+
+    def loadProject(self, location):
+        """
+        Loads the project from the given location.
+
+        @type location: L{str}
+        @param location: The location of a file. Needs to be an absolute URI.
+
+        @rtype: C{Project}
+        @return: The C{Project}
+        @raise FormatterLoadError: If the file couldn't be properly loaded.
+        """
+        raise FormatterLoadError("No Loading feature")
+
+    def saveProject(self, project, location):
+        """
+        Saves the given project to the given location.
+
+        @type project: C{Project}
+        @param project: The Project to store.
+        @type location: L{str}
+        @param location: The location where to store the project. Needs to be
+        an absolute URI.
+        @raise FormatterStoreError: If the file couldn't be properly stored.
+        """
+        raise FormatterSaveError("No Saving feature")
+
+    def canHandle(self, location):
+        """
+        Can this Formatter load the project at the given location.
+
+        @type location: L{str}
+        @param location: The location. Needs to be an absolute C{URI}.
+        @rtype: L{bool}
+        @return: True if this Formatter can load the C{Project}.
+        """
+        raise NotImplementedError
+
+class DefaultFormatter(Formatter):
+
+    pass
diff --git a/pitivi/formatters/format.py b/pitivi/formatters/format.py
new file mode 100644
index 0000000..9ada85a
--- /dev/null
+++ b/pitivi/formatters/format.py
@@ -0,0 +1,73 @@
+# PiTiVi , Non-linear video editor
+#
+#       formatter.format
+#
+# Copyright (c) 2009, Edward Hervey <bilboed bilboed com>
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+"""
+High-level tools for using Formatters
+"""
+
+def load_project(location, formatter=None):
+    """
+    Load the project from the given location.
+
+    If specified, use the given formatter.
+
+    @type location: L{str}
+    @param location: The location of the project. Needs to be an
+    absolute URI.
+    @type formatter: C{Formatter}
+    @param formatter: If specified, try loading the project with that
+    C{Formatter}. If not specified, will try all available C{Formatter}s.
+    @raise FormatterLoadError: If the location couldn't be properly loaded.
+    @return: The loaded C{Project}
+    """
+    pass
+
+def save_project(project, location, formatter=None):
+    """
+    Save the C{Project} to the given location.
+
+    If specified, use the given formatter.
+
+    @type project: C{Project}
+    @param project: The C{Project} to save.
+    @type location: L{str}
+    @param location: The location to store the project to. Needs to
+    be an absolute URI.
+    @type formatter: C{Formatter}
+    @param formatter: The C{Formatter} to use to store the project if specified.
+    If it is not specified, then it will be saved at its original format.
+    @raise FormatterStoreError: If the file couldn't be properly stored.
+    @return: Whether the file was successfully stored
+    @rtype: L{bool}
+    """
+    pass
+
+def can_handle_location(location):
+    """
+    Detects whether the project at the given location can be loaded.
+
+    @type location: L{str}
+    @param location: The location of the project. Needs to be an
+    absolute URI.
+    @return: Whether the location contains a valid C{Project}.
+    @rtype: L{bool}
+    """
+    pass