Your message dated Sun, 6 Jul 2014 02:24:18 +0200
with message-id <[email protected]>
and subject line Fixed
has caused the Debian Bug report #611601,
regarding python-fastimport: high-level documentation
to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact [email protected]
immediately.)
--
611601: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=611601
Debian Bug Tracking System
Contact [email protected] with problems
--- Begin Message ---
Package: python-fastimport
Version: 0.9.0-2
Severity: wishlist
Tags: upstream patch
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?
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 ea05370..8d45eb8 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, 0)
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.rc3
--- End Message ---
--- Begin Message ---
Version: 0.9.3-1
This was fixed upstream in 0.9.3.
signature.asc
Description: Digital signature
--- End Message ---
