python-fastimport: overview documentation

Add some docstrings to help new readers to get started.

Signed-off-by: Jelmer Vernooij <jelmer@samba.org>

diff --git a/fastimport/__init__.py b/fastimport/__init__.py
index 3f2ec5ad1cd887e2044258a3e08e2a0244550458..37265b8deecd4e8b9eef152222b0519c174973ec 100644 (file)
--- a/fastimport/__init__.py
+++ b/fastimport/__init__.py
@@ -13,6 +13,21 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Fastimport streams."""
+"""Fastimport file format parser and generator
+
+This is a Python parser for git's fast-import format.  It was
+originally developed for bzr-fastimport but has been extracted so
+it can be used by other projects.  Use it like so:
+
+   import fastimport.processor
+   import fastimport.parser
+
+   class ImportProcessor(fastimport.processor.ImportProcessor):
+       ...
+
+   parser = fastimport.parser.ImportParser(sys.stdin)
+   processor = ImportProcessor(...)
+   processor.process(parser.parse())
+"""
 
 __version__ = (0, 9, 4)

diff --git a/fastimport/commands.py b/fastimport/commands.py
index c1a4d05642839ebb1e47ea2ce16dd34de4b79e4f..0a0fce5bbb60073a422d58b1674a3b2e03fe0191 100644 (file)
--- a/fastimport/commands.py
+++ b/fastimport/commands.py
@@ -13,7 +13,11 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Import command classes."""
+"""fast-import command classes.
+
+These objects are used by the parser to represent the content of
+a fast-import stream.
+"""
 
 import stat
 
@@ -58,6 +62,8 @@ class ImportCommand(object):
     def dump_str(self, names=None, child_lists=None, verbose=False):
         """Dump fields as a string.
 
+        For debugging.
+
         :param names: the list of fields to include or
             None for all public fields
         :param child_lists: dictionary of child command names to

diff --git a/fastimport/dates.py b/fastimport/dates.py
index 65223f8e3652e43fb3145c0c7c2204d484978ae0..96efcf2c6fb59c4c7a3e9585e1e9f15ead919b6a 100644 (file)
--- a/fastimport/dates.py
+++ b/fastimport/dates.py
@@ -15,7 +15,9 @@
 
 """Date parsing routines.
 
-Each routine returns timestamp,timezone where
+Each routine represents a date format that can be specified in a
+stream using the date-format feature.  The return value is
+timestamp,timezone where
 
 * timestamp is seconds since epoch
 * timezone is the offset from UTC in seconds.

diff --git a/fastimport/processor.py b/fastimport/processor.py
index df00e2dcef0a49ab9f7484a362d857202a9066ba..d71b98fa37e3b6681295f07aaabc7503bc33ed1c 100644 (file)
--- a/fastimport/processor.py
+++ b/fastimport/processor.py
@@ -13,10 +13,21 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Processor of import commands.
+"""Processor for fast-import commands.
 
-This module provides core processing functionality including an abstract class
-for basing real processors on. See the processors package for examples.
+This module provides the skeleton of a fast-import backend.
+To import from a fast-import stream to your version-control system:
+
+ - derive a class from the abstract ImportProcessor class and
+   implement the *_helper methods.
+
+ - parse a fast-import stream into a sequence of commands, for example
+   using the helpers from the parser module.
+
+ - pass that command sequence to the process method of your processor.
+
+See git-fast-import.1 for the meaning of each command and the
+processors package for examples.
 """
 
 import sys
@@ -26,7 +37,7 @@ import errors
 
 
 class ImportProcessor(object):
-    """Base class for import processors.
+    """Base class for fast-import stream processors.
 
     Subclasses should override the pre_*, post_* and *_handler
     methods as appropriate.