From c8995e48d6d61e3286db579d594b9b9df33619ce Mon Sep 17 00:00:00 2001 From: mhagger Date: Sat, 15 Dec 2012 06:40:41 +0000 Subject: [PATCH] Document a subtlety regarding using custom classes in an options file. Because the run_options object is pickled, class instances used within run_options have to be pickleable, which means that they have to be defined at the top level of a Python module (i.e., not within the options file itself). Document this. git-svn-id: http://cvs2svn.tigris.org/svn/cvs2svn/trunk@5408 be7e6eca-30d4-0310-a8e5-ac0d63af7087 --- www/cvs2svn.html | 5 ++++ www/faq.html | 70 +++++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 67 insertions(+), 8 deletions(-) diff --git a/www/cvs2svn.html b/www/cvs2svn.html index 970fa685..bd6b1ceb 100644 --- a/www/cvs2svn.html +++ b/www/cvs2svn.html @@ -439,6 +439,11 @@ this:

-p/--pass/--passes, --dry-run, and --profile.

+

Note: If you want to customize your conversion +using your own Python classes, these classes must be defined in a +separate Python file then imported into the options file. +See the FAQ for more details.

+
diff --git a/www/faq.html b/www/faq.html index 07b32e0c..3ce8624d 100644 --- a/www/faq.html +++ b/www/faq.html @@ -55,6 +55,9 @@
  • I have hundreds of subprojects to convert and my options file is getting huge
    • +
  • How can I define my own class and use it + in my options file?
    • +
  • How can I convert project foo so that trunk/tags/branches are inside of foo?
    • @@ -381,6 +384,51 @@ for project in projects: +

    How can I define my + own class and use it in my options file?

    + +

    It is possible to customize your conversion using arbitrary + Python code. Sometimes this requires you to define your own + Python class. For technical reasons, such classes should not be + defined within the options file but rather in a separate file that + is imported into the options file.

    + +

    [Technical explanation: The problem is that class instances used + in run_options are pickled in pass1 then unpickled in + later passes. (Pickling is a Python mechanism for storing objects + to a file.) But class instances can only be unpickled if the + class can be imported at the time of unpickling. This, in turns, + requires the class to be defined at the top level of a Python + module. The options file is not a valid Python module; + among other things, it is loaded using execfile(), not by being + imported.]

    + +

    So create a separate file with a *.py filename, + like myoptionsclasses.py. In that file, do any imports + needed by your code, then define your class:

    + +
    +from cvs2svn_lib.symbol_transform import SymbolTransform
+
+class MySymbolTransform(SymbolTransform):
+    def transform(self, cvs_file, symbol_name, revision):
+        [...]
+
    + +

    Then, in your main options file, import the class and use it:

    + +
    +from myoptionsclasses import MySymbolTransform
+
+run_options.add_project(
+    [...]
+    symbol_transforms=[
+        MySymbolTransform(),
+        ...
+        ])
+
    + +

    How can I convert project foo so that trunk/tags/branches are inside of foo?

    @@ -539,8 +587,11 @@ class MyPropertySetter(FilePropertySetter): ctx.file_property_setters.append(MyPropertySetter()) -

    See the file cvs2svn_lib/property_setters.py for more - examples.

    +

    Please note that the class must be + defined in a separate file.

    + +

    See the file cvs2svn_lib/property_setters.py for many + examples of property setters.

    I @@ -562,12 +613,12 @@ ctx.file_property_setters.append(MyPropertySetter()) any legal symbol name, which will be used in the conversion instead of the original name.

    -

    To use this feature, you will have to use an options file to start - the conversion. You then write a new SymbolTransform class that - inherits from RegexpSymbolTransform but checks the path before - deciding whether to transform the symbol. Add the following to - your options file:

    +

    To use this feature, you will have to use + an options file to + start the conversion. You then write a new SymbolTransform class + that inherits from RegexpSymbolTransform but checks the path + before deciding whether to transform the symbol. You can do + something like the following:

     from cvs2svn_lib.symbol_transform import RegexpSymbolTransform
@@ -607,6 +658,9 @@ run_options.add_project(
     symbol_transforms=symbol_transforms))
    +

    Please note that the class must be + defined in a separate file.

    +

    This example causes any symbol under "project1" that looks like "release-3_12" to be transformed into a symbol named "project1-release-3.12", whereas if the same symbol appears under -- 2.11.4.GIT