diff options
author | Jonathan Nieder <jrnieder@gmail.com> | 2014-03-01 22:35:43 +0000 |
---|---|---|
committer | Jelmer Vernooij <jelmer@samba.org> | 2014-03-01 22:35:43 +0000 |
commit | 203d9c4f930f841bd06f7830874aa96d748eeebb (patch) | |
tree | ed1945bb95415e92d31b474b7c9911a87b67f248 /fastimport | |
parent | 9d727cb3eef310efa9f4ff04d8cea0ade5539a2d (diff) | |
download | python-fastimport-git-203d9c4f930f841bd06f7830874aa96d748eeebb.tar.gz |
python-fastimport: overview documentation
Add some docstrings to help new readers to get started.
Signed-off-by: Jelmer Vernooij <jelmer@samba.org>
Diffstat (limited to 'fastimport')
-rw-r--r-- | fastimport/__init__.py | 17 | ||||
-rw-r--r-- | fastimport/commands.py | 8 | ||||
-rw-r--r-- | fastimport/dates.py | 4 | ||||
-rw-r--r-- | fastimport/processor.py | 19 |
4 files changed, 41 insertions, 7 deletions
diff --git a/fastimport/__init__.py b/fastimport/__init__.py index 3f2ec5a..37265b8 100644 --- 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 c1a4d05..0a0fce5 100644 --- 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 65223f8..96efcf2 100644 --- 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 df00e2d..d71b98f 100644 --- 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. |