Hi, It can be hard to get started with a new module without some documentation or examples to indicate how it is meant to be used. Maybe some docstrings could help? Patch attached[1]. (Background at [2].)
Thoughts? Jonathan affects python-fastimport [1] Jelmer Vernooij wrote: > At the moment the best way to submit changes is to submit merge > proposals against the Bazaar branch. Hopefully lesser ways also work. ;-) (I have an irrational dislike for complicated contribution procedures.) Applies with "bzr patch -p1". [2] > There's an upstream project on Launchpad that's the preferred address at > the moment: https://launchpad.net/python-fastimport Filing. http://bugs.debian.611601 has the original report.
From 6d2d59767acd265cf19228edc3240050721f1c0b Mon Sep 17 00:00:00 2001
From: Jonathan Nieder <jrnie...@gmail.com>
Date: Sun, 30 Jan 2011 22:42:09 -0600
Subject: [PATCH] python-fastimport: overview documentation
Add some docstrings to help new readers to get started.
No claim of reliability intended. I followed the rule, "when in
doubt, make something up".
---
fastimport/__init__.py | 17 ++++++++++++++++-
fastimport/commands.py | 8 +++++++-
fastimport/dates.py | 4 +++-
fastimport/processor.py | 19 +++++++++++++++----
fastimport/reftracker.py | 8 ++++++--
5 files changed, 47 insertions(+), 9 deletions(-)
diff --git a/fastimport/__init__.py b/fastimport/__init__.py
index 0e2570e..cb23139 100644
--- a/fastimport/__init__.py
+++ b/fastimport/__init__.py
@@ -14,6 +14,21 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-"""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, 1)
diff --git a/fastimport/commands.py b/fastimport/commands.py
index 957928e..28f4974 100644
--- a/fastimport/commands.py
+++ b/fastimport/commands.py
@@ -14,7 +14,11 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-"""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
@@ -59,6 +63,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 ba484ef..bb85f01 100644
--- a/fastimport/dates.py
+++ b/fastimport/dates.py
@@ -16,7 +16,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 2455b4d..37680da 100644
--- a/fastimport/processor.py
+++ b/fastimport/processor.py
@@ -14,10 +14,21 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-"""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
@@ -27,7 +38,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.
diff --git a/fastimport/reftracker.py b/fastimport/reftracker.py
index 3862180..50eeda9 100644
--- a/fastimport/reftracker.py
+++ b/fastimport/reftracker.py
@@ -14,9 +14,13 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+"""Import state: current branch, tips of branches being imported.
-"""Tracker of refs."""
-
+The lines describing parents to a commit in a fast-import stream can
+refer to the tip of the branch being imported (which is the default)
+or the tip of some other branch. This module can be used by
+processors to keep track of the relevant state.
+"""
class RefTracker(object):
--
1.7.4
signature.asc
Description: Digital signature
