Changeset 25

Timestamp:

01/08/07 16:48:50 (3 years ago)

Author:

jjr8

Message:

Implemented support for exposing GeoEco? classes as COM objects (Trac ticket #32). There are still several minor things that are not done; I will open separate tickets for these.

Reorganized the GeoEco?.ArcGIS and GeoEco?.Logging code into classes that are exposed as COM objects, so COM callers can initialize the logging system and pass in their own instance of the ArcGIS geoprocessor.

Added metadata to the GeoEco?.ArcGIS and GeoEco?.Logging modules. The metadata is still not complete for either module.

Changed the default logging level to DEBUG for the duration of the development cycle.

Eliminated the GeoEco?.Tool module and the requirement that classes derive from this module in order to be exposed through ArcGIS or COM. This requirement was not really necessary. Now the only requirement is that a class be instrumented with appropriate metadata.

Pursuant to the change above, I changed some error messages to refer to GeoEco? "functions" rather than "tools". From now on, "tool" is probably best used only when discussing something specific to ArcGIS.

Fixed a bug in GeoEco?.Metadata.PropertyMetadata?.ValidatePropertyAssignment? that caused Python to silently exit when you used a classmethod for the fset method of a property.

Added IsReadOnly? flag to the XML representation of property metadata.

Fixed bugs in GeoEco?.Metadata.MethodMetadata?._GetHasDefault and _GetDefault that caused them to assert when invoked for a varargs or varkw argument.

Added AnyPythonInstance?, PythonSequence?, and PythonTuple? to Types.py.

Files:

• MGET/Trunk/PythonPackage/BuildWin32.cmd (modified) (1 diff)
• MGET/Trunk/PythonPackage/dist/GeoEco-0.1.0a1.win32.exe (modified) (previous)
• MGET/Trunk/PythonPackage/setup.py (modified) (13 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/ArcGIS.py (modified) (15 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/Configuration/Logging.txt (modified) (3 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/Dependencies.py (modified) (3 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/Exceptions.py (modified) (1 diff)
• MGET/Trunk/PythonPackage/src/GeoEco/Logging.py (modified) (6 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/Metadata.py (modified) (17 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/Tool.py (deleted)
• MGET/Trunk/PythonPackage/src/GeoEco/Tools/HelloWorld.py (modified) (7 diffs)
• MGET/Trunk/PythonPackage/src/GeoEco/Types.py (modified) (14 diffs)
• MGET/Trunk/VisualStudioSolutions/CreateArcGISToolbox/Program.cs (modified) (13 diffs)
• MGET/Trunk/VisualStudioSolutions/CreateArcGISToolbox/bin/Release/CreateArcGISToolbox.exe (modified) (previous)
• MGET/Trunk/VisualStudioSolutions/CreateArcGISToolbox/bin/Release/CreateArcGISToolbox.pdb (modified) (previous)

MGET/Trunk/PythonPackage/BuildWin32.cmd

@@ -1 +1 @@
-@echo off
+if not "%DevEnvDir%"=="" goto Build
+call "C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat"
+:Build
-cmd.exe /C setup.py bdist_wininst --install-script=GeoEcoPostInstall.py

MGET/Trunk/PythonPackage/setup.py

@@ -14 +14 @@
-import xml.dom.minidom
-
+
-# Helper functions
-
@@ -49 +50 @@
-            AppendMetadataXMLForModule(submoduleName, p, submodulesNode.appendChild(document.createElement(u'ModuleMetadata')), document)
-
+
-def WriteArcGISWrapperScriptForMethod(moduleName, method, scriptsDir):
-    u"""Write a Python wrapper script to scriptsDir for invoking method from an ArcGIS toolbox."""
@@ -54 +56 @@
-    import GeoEco.ArcGIS
-    
-ToolMetadata
+MethodMetadataForExposureAsArcGISTool
-    fileName = os.path.join(scriptsDir, u'%s.%s.py' % (method.Class.Name, method.Name))
-    print(u'  Writing \"%s\"' % fileName)
-    f = file(fileName, u'w')
-    f.write('import GeoEco.ArcGIS\n')
-ToolFromCommandLine
+MethodFromCommandLineAsArcGISTool
-    f.close()
-
+
-def WriteArcGISWrapperScriptsForMethodsInModule(moduleName, modulePath, scriptsDir):
-flagged for exposure as ArcGIS tools, write Python wrapper scripts to scriptsDir for invoking these methods from an ArcGIS toolbox. If this
+of all classes in the specified module, if the method is flagged for exposure as ArcGIS tool, write a Python wrapper script to scriptsDir for invoking the method from an ArcGIS toolbox. If the specified module
-
-    import GeoEco.Metadata
@@ -90 +93 @@
-                continue
-            WriteArcGISWrapperScriptsForMethodsInModule(submoduleName, p, scriptsDir)
+
+
+def GetIDispatchClassesInModule(moduleName, modulePath):
+    u"""Return all classes in the specified module that are flagged for exposure using the Microsoft COM IDispatch interface. If the specified module is a package, recurse down subpackages and submodules."""
+
+    import GeoEco.Metadata
+
+    # Add all classes from the specified module.
+
+    iDispatchClasses = []    
+    
+    if isinstance(sys.modules[moduleName].__doc__, GeoEco.Metadata.DynamicDocString) and isinstance(sys.modules[moduleName].__doc__.Obj, GeoEco.Metadata.ModuleMetadata):
+        for (className, cls) in sys.modules[moduleName].__dict__.items():
+            if inspect.isclass(cls) and isinstance(cls.__doc__, GeoEco.Metadata.DynamicDocString) and isinstance(cls.__doc__.Obj, GeoEco.Metadata.ClassMetadata) and cls.__doc__.Obj.Module == sys.modules[moduleName].__doc__.Obj and cls.__doc__.Obj.IsExposedByIDispatch:
+                iDispatchClasses.append(cls)
+
+    # If the specified module is a directory, then it is a Python package.
+    # Process the submodules and subpackages.
+
+    if os.path.isdir(modulePath):
+        paths = glob.glob(os.path.join(modulePath, u'*'))
+        for p in paths:
+            if os.path.isfile(p) and p.endswith(u'.py') and os.path.basename(p) != u'__init__.py':
+                submoduleName = moduleName + u'.' + os.path.basename(p)[:-3]
+            elif os.path.isdir(p) and p.lower() != u'.svn' and os.path.isfile(os.path.join(p, u'__init__.py')):
+                submoduleName = moduleName + u'.' + os.path.basename(p)
+            else:
+                continue
+            moreIDispatchClasses = GetIDispatchClassesInModule(submoduleName, p)
+            iDispatchClasses.extend(moreIDispatchClasses)
+
+    # Return a list of classes that are flagged for exposure using IDispatch, so
+    # the caller does not have to enumerate them again.
+
+    return iDispatchClasses    
+
-
-def CopyTree(src, dest):
@@ -220 +259 @@
-        WriteArcGISWrapperScriptsForMethodsInModule(u'GeoEco', sys.modules[u'GeoEco'].__path__[0], os.path.join(arcGISDir, u'Scripts'))
-
+        # TODO: validate that the same tool name is not exposed twice (Trac ticket #29)
+
-        # Create the ArcGIS toolbox.
-
@@ -244 +285 @@
-        packageData[u'GeoEco'].append(os.path.join(u'ArcGISToolbox', u'Scripts', u'*.*'))
-
+    # If running on Windows, generate the COM type library for classes that can
+    # be invoked through COM Automation (IDispatch) interfaces.
+
+    if sys.platform.lower() == u'win32':
+        print(u'')
+        print(u'********************************************************************************')
+        print(u'* Generating the Microsoft COM type library')
+        print(u'********************************************************************************')
+        print(u'')
+
+        # Open the IDL file for writing.
+
+        comDir = os.path.join(srcDir, u'GeoEco', u'COM')
+        idlFilePath = os.path.join(comDir, u'GeoEco.idl')
+        print(u'Opening %s for writing.' % idlFilePath)
+        idlFile = file(idlFilePath, u'w')
+        idlFile.write('// IDL for GeoEco Type Library\n')
+        idlFile.write('//\n')
+        idlFile.write('// GeoEco is a Python package that provides geospatial ecology tools.\n')
+        idlFile.write('// Many of these tools are exposed as COM classes. Each class has a\n')
+        idlFile.write('// ProgID beginning with "GeoEco." and exposes a dual interface.\n')
+        idlFile.write('// Late-binding clients such as script engines can invoke the classes\n')
+        idlFile.write('// through the IDispatch interface, while early-binding clients such\n')
+        idlFile.write('// as C# can import the GeoEco Type Library and invoke the classes\n')
+        idlFile.write('// through the more-efficient vtable interface.\n')
+        idlFile.write('//\n')
+        idlFile.write('// This IDL file defines all of the interfaces and classes exported by\n')
+        idlFile.write('// the GeoEco type library.\n')
+        idlFile.write('\n')
+        idlFile.write('import "oaidl.idl";\n')
+        idlFile.write('import "ocidl.idl";\n')
+        idlFile.write('\n')
+
+        # Obtain a list of all of the classes flagged for exposure through COM
+        # IDispatch. Validate the classes' metadata. Also validate that each
+        # class has a unique name across the entire set of classes, regardless
+        # of which module it appears in. This means developers cannot
+        # disambiguate classes with the same names using the Python module
+        # hierarchy. The benefit of this restriction is that we don't have to
+        # generate multiple type libraries, or a single type library that
+        # prepends the full list of module names to the class name.
+
+        print(u'Validating classes flagged for exposure by IDispatch:')
+
+        import pythoncom
+        import GeoEco.COM
+
+        classDict = {}
+        guidDict = {}
+
+        iDispatchClasses = GetIDispatchClassesInModule(u'GeoEco', sys.modules[u'GeoEco'].__path__[0])
+        for cls in iDispatchClasses:
+            GeoEco.COM.ValidateClassMetadata(cls)
+            classMetadata = cls.__doc__.Obj
+            
+            if classDict.has_key(classMetadata.Name):
+                sys.exit(u'Two classes flagged for exposure by IDispatch have the same class name: %s.%s and %s.%s. To be exposed by IDispatch, each class must have a unique name, regardless of what module it appears in. Please change the name of one of these classes.' % (classMetadata.Module.Name, classMetadata.Name, classDict[classMetadata.Name].Module.Name, classDict[classMetadata.Name].Name))
+            classDict[classMetadata.Name] = classMetadata
+            
+            if guidDict.has_key(classMetadata.COMIID):
+                sys.exit(u'Two classes flagged for exposure by IDispatch are using the same GUID %s: %s.%s is using it for COMIID and %s.%s is using it for %s. To be exposed by IDispatch, each class must have a unique GUID for COMIID and COMCLSID. Here is a new unique GUID you can use: %s' % (classMetadata.COMIID, classMetadata.Module.Name, classMetadata.Name, guidDict[classMetadata.COMIID][1].Module.Name, guidDict[classMetadata.COMIID][1].Name, guidDict[classMetadata.COMIID][0], repr(unicode(pythoncom.CreateGuid()))))
+            guidDict[classMetadata.COMIID] = (u'COMIID', classMetadata)
+            
+            if guidDict.has_key(classMetadata.COMCLSID):
+                sys.exit(u'Two classes flagged for exposure by IDispatch are using the same GUID %s: %s.%s is using it for COMCLSID and %s.%s is using it for %s. To be exposed by IDispatch, each class must have a unique GUID for COMIID and COMCLSID. Here is a new unique GUID you can use: %s' % (classMetadata.COMIID, classMetadata.Module.Name, classMetadata.Name, guidDict[classMetadata.COMIID][1].Module.Name, guidDict[classMetadata.COMIID][1].Name, guidDict[classMetadata.COMIID][0], repr(unicode(pythoncom.CreateGuid()))))
+            guidDict[classMetadata.COMIID] = (u'COMCLSID', classMetadata)
+            
+            print('  %s.%s as ProgID %s' % (cls.__doc__.Obj.Module.Name, cls.__doc__.Obj.Name, cls.__doc__.Obj.COMVersionIndependentProgID))
+
+        # Write the interface definitions to the IDL file.
+
+        print(u'Writing interface definitions to %s.' % idlFilePath)
+        for cls in iDispatchClasses:
+            idlFile.write(GeoEco.COM.GetIDLInterfaceDefinitionFromMetadata(cls.__doc__.Obj))
+            idlFile.write('\n')
+
+        # Write type library header to the IDL file.
+
+        idlFile.write('[\n')
+        idlFile.write('    uuid(%s),\n' % GeoEco.COM.TypeLibraryGUID[1:-1])
+        idlFile.write('    version(%i.%i),\n' % (GeoEco.COM.TypeLibraryVersion[0], GeoEco.COM.TypeLibraryVersion[1]))
+        idlFile.write('    helpstring("GeoEco %i.%i Type Library")\n' % (GeoEco.COM.TypeLibraryVersion[0], GeoEco.COM.TypeLibraryVersion[1]))    
+        idlFile.write(']\n')
+        idlFile.write('library GeoEco\n')
+        idlFile.write('{\n')
+        idlFile.write('    importlib("stdole32.tlb");\n')
+        idlFile.write('    importlib("stdole2.tlb");\n')
+
+        # Write the coclass definitions to the IDL file.
+
+        for cls in iDispatchClasses:
+            idlFile.write('\n')
+            idlFile.write('    [\n')
+            idlFile.write('        uuid(%s),\n' % cls.__doc__.Obj.COMCLSID[1:-1])
+            idlFile.write('        helpstring("%s Class")\n' % cls.__doc__.Obj.Name)
+            idlFile.write('    ]\n')
+            idlFile.write('    coclass %s\n' % cls.__doc__.Obj.Name)
+            idlFile.write('    {\n')
+            idlFile.write('        [default] interface I%s;\n' % cls.__doc__.Obj.Name)
+            idlFile.write('    };\n')
+
+        # Close the IDL file.        
+
+        idlFile.write('};\n')
+        idlFile.close()
+
+        # Execute the MIDL compiler on the IDL file to produce the TLB file.
+
+        tlbFilePath = os.path.splitext(idlFilePath)[0] + u'.tlb'        
+
+        args = [u'midl.exe', u'/out', os.path.dirname(idlFilePath), u'/tlb', tlbFilePath, u'/win32', idlFilePath]
+        print('Invoking %s' % ' '.join(args))
+        try:
+            p = subprocess.Popen(args)
+        except WindowsError, e:
+            if e.errno == 2:
+                print(e.__class__.__name__ + u': ' + unicode(e))
+                sys.exit(u'The most common cause for failure here is forgetting to register the Microsoft Visual Studio environment variables. This is usually best accomplished by running "C:\\Program Files\\Microsoft Visual Studio 8\\Common7\\Tools\\vsvars32.bat" prior to executing setup.py.')
+            else:
+                raise
+        retcode = p.wait()
+        if retcode != 0:
+            sys.exit(u'midl.exe failed and returned exit code %i.' % retcode)
+        for ext in [u'_i.c', u'_p.c', u'.h']:
+            if os.path.exists(os.path.splitext(idlFilePath)[0] + ext):
+                os.remove(os.path.splitext(idlFilePath)[0] + ext)
+        if os.path.exists(os.path.join(os.path.dirname(idlFilePath), u'dlldata.c')):
+            os.remove(os.path.join(os.path.dirname(idlFilePath), u'dlldata.c'))
+
+        packageData[u'GeoEco'].append(os.path.join(u'COM', u'*.*'))
+
-    # If running on Windows, generate the postinstall script.
-
@@ -251 +423 @@
-        print(u'* Generating the Windows postinstall script')
-        print(u'********************************************************************************')
-
+
+
+
+
+
+
+
-
-        postInstallFilePath = os.path.join(srcDir, u'GeoEcoPostInstall.py')
@@ -270 +448 @@
-import GeoEco
-geoEcoRoot = os.path.dirname(sys.modules['GeoEco'].__file__)
+
+###############################################################################
+#  INPUT DATA
+###############################################################################
+
+classesForCOMRegistration = """ + classesForCOMRegistration + """
-
-###############################################################################
@@ -308 +492 @@
-        import win32process
-    except:
-the package
+pywin32 for your version of Python
-
-    # Ensure the ArcGIS is installed by reading the InstallDir from the registry.
@@ -366 +550 @@
-    return True
-
+def RegisterClassesAsCOMIDispatchServers():
+
+    # Import pywin32 modules that we need.
+    
+    try:
+        import pythoncom
+        import win32com.server.register
+    except:
+        sys.exit('ERROR: Python for Windows Extensions (pywin32) is not installed. GeoEco requires this Python package. Please uninstall GeoEco, download pywin32 for your version of Python from http://sourceforge.net/projects/pywin32, install it, and install GeoEco again.')
+
+    # Register the classes.
+
+    success = True
+    import GeoEco.COM
+    for [moduleName, className] in classesForCOMRegistration:
+        if not GeoEco.COM.RegisterIDispatchServerUsingClassMetadata(moduleName, className):
+            success = False
+
+    # Register the type library.
+
+    tlbFile = os.path.join(os.path.dirname(sys.modules['GeoEco.COM'].__file__), 'COM', 'GeoEco.tlb')    
+    try:
+        tli = pythoncom.LoadTypeLib(tlbFile)
+    except Exception, e:
+        print('WARNING: Failed to load the GeoEco COM type library. Since the library could not be loaded, it will not be registered with COM, and you will not be able to call GeoEco objects from early-bound programming languages such as C#. You can try registration again by uninstalling and reinstalling GeoEco. The pythoncom.LoadTypeLib(\\'%s\\') function reported: %s: %s' % (tlbFile, e.__class__.__name__, str(e)))
+        success = False
+
+    if success:        
+        try:
+            pythoncom.RegisterTypeLib(tli, tlbFile)
+        except Exception, e:
+            print('WARNING: Failed to register the GeoEco COM type library. You will not be able to call GeoEco objects from early-bound programming languages such as C#. You can try registration again by uninstalling and reinstalling GeoEco. The pythoncom.RegisterTypeLib(tli, \\'%s\\') function reported: %s: %s' % (tlbFile, e.__class__.__name__, str(e)))
+            success = False
+    
+    return success
+
+def UnregisterClassesAsCOMIDispatchServers():
+
+    # Import pywin32 modules that we need.
+    
+    try:
+        import pythoncom
+        import win32com.server.register
+    except:
+        return
+
+    # Unregister the classes.
+
+    import GeoEco.COM
+    for [moduleName, className] in classesForCOMRegistration:
+        GeoEco.COM.UnregisterIDispatchServerUsingClassMetadata(moduleName, className)
+
+    # Unregister the type library:
+
+    try:
+        pythoncom.UnRegisterTypeLib('""" + GeoEco.COM.TypeLibraryGUID + '\', ' + str(GeoEco.COM.TypeLibraryVersion[0]) + ', ' + str(GeoEco.COM.TypeLibraryVersion[1]) + ', ' + str(GeoEco.COM.TypeLibraryLCID) + """, pythoncom.SYS_WIN32)
+    except:
+        pass
+
-###############################################################################
-#  MAIN SCRIPT
@@ -374 +617 @@
-if len(sys.argv) >= 2 and sys.argv[1].lower() == '-install':
-    arcGISToolboxInstalled = RegisterToolboxWithArcCatalog('register')
-
-
+
+
+
-        print('All installation tasks completed successfully.')
-    else:
@@ -386 +630 @@
-elif len(sys.argv) >= 2 and sys.argv[1].lower() == '-remove':
-    RegisterToolboxWithArcCatalog('unregister')
+    UnregisterClassesAsCOMIDispatchServers()
-
-# If argv[1] is absent or unrecognized, report an error.
@@ -423 +668 @@
-    print(u'Removing directory %s...' % os.path.join(setupDir, u'build'))
-    shutil.rmtree(os.path.join(setupDir, u'build'), False)
+    print(u'')
+    print(u'***** BUILD SUCCESSFUL *****')
-
-if __name__ == u'__main__':

MGET/Trunk/PythonPackage/src/GeoEco/ArcGIS.py

@@ -12 +12 @@
-import GeoEco.Logging
-from GeoEco.Metadata import *
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-class ArcGISVersion(Dependency):
@@ -83 +280 @@
-    def Initialize(self):
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        else:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
-
-        # Validate the class and method metadata.
-
-
-
-
+
+
-        cls = sys.modules[moduleName].__dict__[className]
-        assert isinstance(cls.__doc__, DynamicDocString) and isinstance(cls.__doc__.Obj, ClassMetadata), u'The __doc__ attribute of class %s must be an instance of DynamicDocString, and that Obj property of that instance must be an instance of ClassMetadata.' % className
@@ -211 +346 @@
-
-
-ToolFromCommandLine
+MethodFromCommandLineAsArcGISTool
-
-    # Initialize the logging system.
-
-    import GeoEco.Logging
-InitializeLogging
+Logger.Initialize
-    try:
-
-
-tool
+Logger.
+
+methods
-        # package was built, but we do it again here for safety.
-
-        __import__(moduleName, globals(), locals())        
-ToolMetadata
+MethodMetadataForExposureAsArcGISTool
-
-        # Determine whether we were invoked from an ArcGIS GUI application, in
-        # which case we can use the geoprocessor's GetParameterAsText API to
-tool
+method
-        # GUI, then this API won't work, and we have to get the parameters from
-        # sys.argv. GetParameterAsText is better because it doesn't strip out
@@ -245 +380 @@
-        methodMetadata = getattr(cls, methodName).__doc__.Obj
-        expectedParamCount = len(methodMetadata.Arguments) + len(methodMetadata.Results) - 1        # Subtract 1 because the "self" or "cls" parameter is not exposed in ArcGIS
-globals()[u'Geoprocessor']
+GeoprocessorManager.GetWrappedGeoprocessor()
-        if geoprocessor.ParameterCount == expectedParamCount:
-            useSysArgv = False
@@ -290 +425 @@
-        for i in range(len(methodMetadata.Results)):
-            if locals()[u'ret%s' % i] is not None:
-globals()[u'Geoprocessor']
+GeoprocessorManager.GetWrappedGeoprocessor()
-            else:
-globals()[u'Geoprocessor']
+GeoprocessorManager.GetWrappedGeoprocessor()
-
-    # If we caught an exception, log it as an error if the logger level is set
@@ -300 +435 @@
-        try:
-            if logging.getLogger(u'GeoEco').getEffectiveLevel() <= logging.DEBUG:
-
+ger.
-            else:
-
+ger.
-        except:
-            pass
@@ -310 +445 @@
-
-    sys.exit(0)
-
-
-# Private attributes, functions and classes that implement the public interface.
-
-_RealGeoprocessor = None        # The geoprocessor instance obtained from ArcGIS, not wrapped by a _ArcGISObjectWrapper instance.
-_ArcGISMajorVersion = None     # Major version number of ArcGIS that is installed on this machine
-_ArcGISMinorVersion = None     # Minor version number of ArcGIS that is installed on this machine
-_ArcGISServicePack = None      # Service pack number of ArcGIS that is installed on this machine
-
-
-def _InitializeGeoprocessor(dependency=None):
-    assert globals()[u'Geoprocessor'] is None and globals()[u'_RealGeoprocessor'] is None or globals()[u'Geoprocessor'] is not None and globals()[u'_RealGeoprocessor'] is not None
-    assert isinstance(dependency, (types.NoneType, Dependency))
-    
-    # Return immediately the geoprocessor has already been initialized.
-
-    if globals()[u'Geoprocessor'] is not None:
-        return
-        
-    # First try to import the arcgisscripting package, which was
-    # introduced in ArcGIS 9.2.
-
-    arcgissscriptingImported = True
-    try:
-        import arcgisscripting
-    except Exception, e:
-        arcgissscriptingImported = False
-
-    # If we succesfully imported the arcgisscripting package, use it to
-    # create the geoprocessor object.
-
-    realGeoprocessor = None
-
-    if arcgissscriptingImported:
-        error = None
-        try:
-            realGeoprocessor = arcgisscripting.create()
-        except Exception, e:
-            error = (u'%s: %s' % e.__class__.__name__, unicode(e)).strip()
-        if realGeoprocessor is None:
-            message = _(u'This tool requires ESRI ArcGIS. The tool successfully imported the Python arcgisscripting package, suggesting that ArcGIS 9.2 or later is installed. But the arcgisscripting.create() function')
-            if error is None:
-                message = _(u'%s did not return the geoprocessor object (it returned None without raising an exception). Please verify that ArcGIS is properly installed.') % message
-            else:
-                message = _(u'%s raised an exception. Please verify that ArcGIS is properly installed. The exception was: %s') % (message, error)
-            raise SoftwareNotInstalledError(message, dependency)
-
-    # If we failed to import the arcgisscripting package, try the old
-    # technique of creating the IDispatch COM object.
-
-    else:
-            
-        # The IDispatch technique only works on Windows. Fail if this is
-        # not Windows.
-
-        if platform.system().lower() != u'windows':
-            raise SoftwareNotInstalledError(_(u'This tool requires ESRI ArcGIS, which does not appear to be installed. If ArcGIS is not supported on your operating system, you must run this tool on an operating system that does support it.'), dependency)
-
-        # Import the Python COM libraries.
-        
-        try:
-            import pythoncom
-        except Exception, e:
-            raise SoftwareNotInstalledError(_(u'This tool requires ESRI ArcGIS. ArcGIS  9.2 or a later version does not appear to be installed, because the Python arcgisscripting package could not be imported. A prior version might be installed, but in order for GeoEco to communicate with it, you must install the "Python for Windows extensions" Python package for the running version of Python (%s.%s). This package does not appear to be installed. It may be available at http://sourceforge.net/projects/pywin32. Debugging information: the Python statement "__import__(\'pythoncom\')" raised %s: %s') % (unicode(platform.python_version_tuple()[0]), unicode(platform.python_version_tuple()[1]), e.__class__.__name__, unicode(e)), dependency)
-        
-        try:
-            import win32com.client
-        except Exception, e:
-            raise SoftwareNotInstalledError(_(u'This tool requires ESRI ArcGIS. ArcGIS 9.2 or a later version does not appear to be installed, because the Python arcgisscripting package could not be imported. A prior version might be installed, but in order for GeoEco to communicate with it, you must install the "Python for Windows extensions" Python package for the running version of Python (%s.%s). This package does not appear to be installed. It may be available at http://sourceforge.net/projects/pywin32. Debugging information: the Python statement "__import__(\'win32com.client\')" raised %s: %s') % (unicode(platform.python_version_tuple()[0]), unicode(platform.python_version_tuple()[1]), e.__class__.__name__, unicode(e)), dependency)
-
-        # Create the IDispatch object.
-
-        progID = 'esriGeoprocessing.GPDispatch'
-        
-        try:
-            realGeoprocessor = win32com.client.Dispatch(progID)
-        except pythoncom.com_error, (hr, msg, exc, arg):
-            raise SoftwareNotInstalledError(_(u'This tool requires ESRI ArcGIS, which does not appear to be installed. This tool was unable to import the arcgisscripting Python module, indicating that ArcGIS 9.2 or later is not installed. It was also unable to create the %s COM object, indicating that ArcGIS 9.0 or 9.1 is not installed. Debugging information: win32com.client.Dispatch(\'%s\') raised the exception: %s') % (progID, _FormatCOMError(hr, msg, exc, arg)), dependency)
-        except Exception, e:
-            raise SoftwareNotInstalledError(_(u'This tool requires ESRI ArcGIS, which does not appear to be installed. This tool was unable to import the arcgisscripting Python module, indicating that ArcGIS 9.2 or later is not installed. It was also unable to create the %s COM object, indicating that ArcGIS 9.0 or 9.1 is not installed. Debugging information: win32com.client.Dispatch(\'%s\') raised the exception: %s: %s') % (progID, e.__class__.__name__, unicode(e)), dependency)
-
-    # We successfully created the geoprocessor object.
-
-    SetRealGeoprocessor(realGeoprocessor)
-
-
@@ -531 +582 @@
-                except com_error, (hr, msg, exc, arg):
-                    self._LogReturnedGeoprocessingMessages()            # Most likely there are none, but try it anyway.
-tool or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this tool or ArcGIS, please contact the author of this tool
+function or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this function or ArcGIS, please contact the author of this function
-
-            # If we did not import pythoncom, set the value and allow the outer
@@ -549 +600 @@
-        except Exception, e:
-            self._LogReturnedGeoprocessingMessages()            # Most likely there are none, but try it anyway.
-tool or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this tool or ArcGIS, please contact the author of this tool
+function or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this function or ArcGIS, please contact the author of this function
-
-        # If it is a method, create a wrapper, add it to our dictionary of
@@ -625 +676 @@
-                    else:
-                        valueStr = repr(value)
-tool or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this tool or ArcGIS, please contact the author of this tool
+function or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this function or ArcGIS, please contact the author of this function
-
-            # If we did not import pythoncom, set the value and allow the outer
@@ -647 +698 @@
-            else:
-                valueStr = repr(value)
-tool or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this tool or ArcGIS, please contact the author of this tool
+function or ArcGIS itself. Please check your inputs and try again. Also review any preceding error messages and the detailed error information that appears at the end of this message. If you suspect a programming mistake in this function or ArcGIS, please contact the author of this function
-
-        # Log the set value.
@@ -699 +750 @@
-                except com_error, (hr, msg, exc, arg):
-                    self._LogReturnedGeoprocessingMessages()
-tool or ArcGIS, please contact the author of this tool
+function or ArcGIS, please contact the author of this function
-
-            # If we did not import pythoncom, invoke the method and allow the
@@ -717 +768 @@
-        except Exception, e:
-            self._LogReturnedGeoprocessingMessages()
-tool or ArcGIS, please contact the author of this tool
+function or ArcGIS, please contact the author of this function
-
-        # The method executed successfully. Log any geoprocessing messages it
@@ -753 +804 @@
-        i = 0
-        try:
-tReal
+oprocessorManager.Get
-            while i < realGeoprocessor.MessageCount:
-                sev = realGeoprocessor.GetSeverity(i)
@@ -841 +892 @@
-        u'fidset' : None,
-        u'PropertySet' : None}
+
+
+###############################################################################
+# Metadata: module
+###############################################################################
+
+AddModuleMetadata(shortDescription=_(u'Provides utility functions for interacting with the ESRI ArcGIS software package.'))
+
+###############################################################################
+# Metadata: GeoprocessorManager class
+###############################################################################
+
+AddClassMetadata(GeoprocessorManager,
+    shortDescription=_(u'Manages the instance of the ArcGIS geoprocessor object used whenever any GeoEco function needs to invoke ArcGIS tools.'),
+    isExposedByIDispatch=True,
+    comIID=u'{3DAAF9BD-2C7F-4A0B-8AB1-8975103F3E78}',
+    comCLSID=u'{6E4B25C1-0E1D-496B-A661-AC75ADCB24C8}')
+
+# Public properties
+
+AddPropertyMetadata(GeoprocessorManager.Geoprocessor,
+    typeMetadata=AnyPythonInstance(canBeNone=True),
+    shortDescription=_(u'The ArcGIS geoprocessor object used whenever any GeoEco function needs to invoke ArcGIS tools.'),
+    longDescription=_(
+u"""This property is a singleton; all Python modules running in the same
+instance of the Python interpreter share the same value for this property. This
+property remains empty until it is explicitly set, or the InitializeGeoprocessor
+method is explicitly invoked, or a GeoEco function that has a dependency on
+ArcGIS is invoked (in which case it will invoke InitializeGeoprocessor).
+
+If you want to invoke GeoEco functions from your own ArcGIS geoprocessing script
+and you have already obtained a geoprocessor object, you should set this
+property to that object before invoking any other GeoEco functions. Failing to
+do so will cause GeoEco to allocate its own geoprocessor object, which can yield
+unpredictable results. (As far as I can tell, the ArcGIS tools still work
+correctly, but log messages do not end up in the ArcGIS GUIs.)
+
+If your geoprocessing script has not yet obtained the geoprocessor object, you
+may allow the GeoEco functions to obtain one when they first need it and then
+retrieve it by getting the value of this property.
+
+If you want to invoke GeoEco functions from something that is not a
+"geoprocessing script" (a program that does not invoke any ArcGIS
+geoprocessing tools directly), then you should ignore this property and
+allow the GeoEco functions to obtain and use their own geoprocessor object.
+
+See the documentation for InitializeGeoprocessor for more information about this
+property."""),
+    devTeamNotes=_(
+u"""Generally, GeoEco functions should *not* use this property; they should use
+WrappedGeoprocessor instead. That property implements a wrapper around the
+geoprocessor that logs debug messages every time the geoprocessor is invoked."""),
+    isExposedByIDispatch=True)
+
+AddPropertyMetadata(GeoprocessorManager.WrappedGeoprocessor,
+    typeMetadata=AnyPythonInstance(canBeNone=True),
+    shortDescription=_(u'The Geoprocessor property, wrapped by a class that logs messages whenever the geoprocessor is accessed.'),
+    longDescription=_(
+u"""This property is a singleton; all Python modules running in the same
+instance of the Python interpreter share the same value for this property. It is
+initialized whenever the Geoprocessor property is initialized; see the
+documentation for that property for more information.
+
+This property is actually a wrapper class around the ArcGIS geoprocessor object.
+The wrapper exports the same interface as the wrapped object but logs a debug
+message every time a method is invoked or a property is accessed. By default,
+these debug messages are discarded by the GeoEco logging infrastructure. You can
+enable them by initializing the Logger class with a custom configuration file
+or by editing the default configuration file. See the Logger class documentation
+for more information.
+
+All GeoEco functions use WrappedGeoprocessor to access the geoprocessor, rather
+than the Geoprocessor property, so that debug messages are reported whenever any
+function accesses the geoprocessor. External callers are welcome to use
+WrappedGeoprocessor as well, but they should consider using Geoprocessor
+instead, to completely eliminate the chance that a bug in the wrapper would
+affect their code."""),
+    devTeamNotes=_(u'Generally, GeoEco functions should use this property rather than the Geoprocessor property.'),
+    isExposedByIDispatch=True)
+
+AddPropertyMetadata(GeoprocessorManager.ArcGISMajorVersion,
+    typeMetadata=PythonInteger(canBeNone=True),
+    shortDescription=_(u'The major version number for ArcGIS, if it is installed on the machine.'),
+    longDescription=_(u'This property is empty if ArcGIS is not installed on the machine.'),
+    isExposedByIDispatch=True)
+
+AddPropertyMetadata(GeoprocessorManager.ArcGISMinorVersion,
+    typeMetadata=PythonInteger(canBeNone=True),
+    shortDescription=_(u'The minor version number for ArcGIS, if it is installed on the machine.'),
+    longDescription=_(u'This property is empty if ArcGIS is not installed on the machine.'),
+    isExposedByIDispatch=True)
+
+AddPropertyMetadata(GeoprocessorManager.ArcGISServicePack,
+    typeMetadata=PythonInteger(canBeNone=True),
+    shortDescription=_(u'The service pack number for ArcGIS, if it is installed on the machine.'),
+    longDescription=_(u'This property is empty if ArcGIS is not installed on the machine.'),
+    isExposedByIDispatch=True)
+
+# Public method: GetGeoprocessor
+
+AddMethodMetadata(GeoprocessorManager.GetGeoprocessor,
+    shortDescription=_(u'Returns the value of the Geoprocessor property.'))
+
+AddArgumentMetadata(GeoprocessorManager.GetGeoprocessor, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddResultMetadata(GeoprocessorManager.GetGeoprocessor, u'geoprocessor',
+    typeMetadata=AnyPythonInstance(canBeNone=True),
+    description=_(u'The value of the Geoprocessor property.'))
+
+# Public method: SetGeoprocessor
+
+AddMethodMetadata(GeoprocessorManager.SetGeoprocessor,
+    shortDescription=_(u'Sets the value of the Geoprocessor property.'))
+
+AddArgumentMetadata(GeoprocessorManager.SetGeoprocessor, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddArgumentMetadata(GeoprocessorManager.SetGeoprocessor, u'geoprocessor',
+    typeMetadata=AnyPythonInstance(),
+    description=_(u'The ArcGIS geoprocessor object obtained from COM or the arcgisscripting Python module. See the documentation for the Geoprocessor property for more information.'))
+
+# Public method: GetWrappedGeoprocessor
+
+AddMethodMetadata(GeoprocessorManager.GetWrappedGeoprocessor,
+    shortDescription=_(u'Returns the value of the WrappedGeoprocessor property.'))
+
+AddArgumentMetadata(GeoprocessorManager.GetWrappedGeoprocessor, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddResultMetadata(GeoprocessorManager.GetWrappedGeoprocessor, u'geoprocessor',
+    typeMetadata=AnyPythonInstance(canBeNone=True),
+    description=_(u'The value of the WrappedGeoprocessor property.'))
+
+# Public method: GetArcGISMajorVersion
+
+AddMethodMetadata(GeoprocessorManager.GetArcGISMajorVersion,
+    shortDescription=_(u'Returns the value of the ArcGISMajorVersion property.'))
+
+AddArgumentMetadata(GeoprocessorManager.GetArcGISMajorVersion, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddResultMetadata(GeoprocessorManager.GetArcGISMajorVersion, u'majorVersion',
+    typeMetadata=PythonInteger(canBeNone=True),
+    description=_(u'The value of the ArcGISMajorVersion property.'))
+
+# Public method: GetArcGISMinorVersion
+
+AddMethodMetadata(GeoprocessorManager.GetArcGISMinorVersion,
+    shortDescription=_(u'Returns the value of the ArcGISMinorVersion property.'))
+
+AddArgumentMetadata(GeoprocessorManager.GetArcGISMinorVersion, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddResultMetadata(GeoprocessorManager.GetArcGISMinorVersion, u'minorVersion',
+    typeMetadata=PythonInteger(canBeNone=True),
+    description=_(u'The value of the ArcGISMinorVersion property.'))
+
+# Public method: GetArcGISServicePack
+
+AddMethodMetadata(GeoprocessorManager.GetArcGISServicePack,
+    shortDescription=_(u'Returns the value of the ArcGISServicePack property.'))
+
+AddArgumentMetadata(GeoprocessorManager.GetArcGISServicePack, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddResultMetadata(GeoprocessorManager.GetArcGISServicePack, u'servicePack',
+    typeMetadata=PythonInteger(canBeNone=True),
+    description=_(u'The value of the ArcGISMinorVersion property.'))
+
+# Public method: InitializeGeoprocessor
+
+AddMethodMetadata(GeoprocessorManager.InitializeGeoprocessor,
+    shortDescription=_(u'Initializes the Geoprocessor property with a new ArcGIS geoprocessor object.'),
+    longDescription=_(
+u"""Generally, this method should only be invoked by GeoEco classes. There is
+no need for external callers to invoke this function. They should allow GeoEco
+classes to invoke it internally, or obtain their own goeprocessor object from
+ArcGIS and then set the Geoprocessor property.
+
+If the Geoprocessor property is not empty, this method returns without doing
+anything. If it is empty, this method attempts to obtain a geoprocessor object
+using the following procedure:
+
+* Import the arcgisscripting Python package and invoke the create method. This
+  will succeed if ArcGIS 9.2 or later is installed on the machine. If this
+  succeeds, the returned object is an unknown type. (Note: because I have not
+  tried ArcGIS 9.2 yet, I don't know what kind of object is returned. If it is
+  not an IDispatch interface, then it cannot be returned to COM callers. If you
+  are calling InitializeGeoprocessor using COM, I am not sure what will happen.
+  I will investigate this as soon as I can install ArcGIS 9.2.)
+
+* If the step above fails, create the "esriGeoprocessing.GPDispatch" COM object
+  using the Dispatch function provided by the win32com.client Python package.
+  If this succeeds, the returned object is the COM IDispatch interface for the
+  geoprocessor object."""),
+    isExposedByIDispatch=True)
+
+AddArgumentMetadata(GeoprocessorManager.InitializeGeoprocessor, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+# Public method: InitializeGeoprocessorForDependency
+
+AddMethodMetadata(GeoprocessorManager.InitializeGeoprocessorForDependency,
+    shortDescription=_(u'Initializes the Geoprocessor property with a new ArcGIS geoprocessor object on behalf of the specified dependency declared by a GeoEco class method.'),
+    longDescription=_(u'This method should only be invoked directly by the GeoEco.ArcGIS.ArcGISVersion class.'))
+
+AddArgumentMetadata(GeoprocessorManager.InitializeGeoprocessorForDependency, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=GeoprocessorManager),
+    description=_(u'%s class or an instance of it.') % GeoprocessorManager.__name__)
+
+AddArgumentMetadata(GeoprocessorManager.InitializeGeoprocessorForDependency, u'dependency',
+    typeMetadata=PythonClassInstance(cls=GeoEco.Metadata.Dependency, canBeNone=True),
+    description=_(u'An instance of the %s class, or None if the invocation is not occurring on behalf of a dependency.') % GeoEco.Metadata.Dependency.__name__)

MGET/Trunk/PythonPackage/src/GeoEco/Configuration/Logging.txt

@@ -23 +23 @@
-# impossible to track them down. For this reason, ALWAYS make a backup
-# copy of your file and change JUST A LITTLE AT A TIME so that
-d
+
-
-
+
+
-
-[handlers]
@@ -54 +55 @@
-
-[loggers]
-
+,COM
-
-# Log GeoEco informational, warning and error messages to the console.
-# and to ArcGIS. To log debug messages as well, change "level=INFO"
-# to "level=DEBUG". But rather than editing the default GeoEco logging
-
+
+
+
+
+
-
-[logger_GeoEco]
-INFO
+DEBUG
-handlers=Console,ArcGIS
-propagate=0
@@ -68 +73 @@
-
-# Only log warnings and errors from GeoEco.ArcGIS. Change "level=WARNING"
-
-
+
+
+
+
+
+
+
+
-
-[logger_ArcGIS]
-INFO
+DEBUG
-handlers=Console,ArcGIS
-propagate=0
-qualname=GeoEco.ArcGIS
+
+# Only log warnings and errors from GeoEco.COM. Change "level=WARNING"
+# to "level=DEBUG" to see a complete low-level trace of calls to properties and
+# methods of GeoEco classes made through COM. This is useful for debugging
+# obscure COM problems but not much else.
+#
+# WARNING: *DO NOT* add ArcGIS to the list of handlers; you will create an
+# infinite loop!
+#
+# Note: During the initial GeoEco development cycle, we are setting level=DEBUG
+# instead of level=WARNING.
+
+[logger_COM]
+level=DEBUG
+handlers=Console
+propagate=0
+qualname=GeoEco.COM
-
-# Log warnings and errors from any non-GeoEco component to the console.

MGET/Trunk/PythonPackage/src/GeoEco/Dependencies.py

@@ -51 +51 @@
-                if self.MinimumServicePack > 0:
-                    osName = _(u'%s Service Pack %i') % (osName, self.MinimumServicePack)
-tool
+function
-
-            
@@ -66 +66 @@
-        patchlevel = self.__ParseVersionNumber(v[2])
-        if self.MinimumVersion[0] > major or self.MinimumVersion[0] == major and self.MinimumVersion[1] > minor or self.MinimumVersion[0] == major and self.MinimumVersion[1] == minor and self.MinimumVersion[2] > patchlevel:
-tool
+function
-
-    @classmethod
@@ -97 +97 @@
-        except Exception, e:
-            if self.DisplayName is None:
-tool
+function
-            else:
-tool
+function
-            if self.CheeseShopName is not None and self.AlternateURL is None:
-                message = _(u'%s The package may be available at http://www.python.org/pypi/%s.') % (message, self.CheeseShopName)

MGET/Trunk/PythonPackage/src/GeoEco/Exceptions.py

@@ -19 +19 @@
-
-    def __unicode__(self):
-tool
+function
-
-    def AsCOMException():

MGET/Trunk/PythonPackage/src/GeoEco/Logging.py

@@ -7 +7 @@
-import GeoEco
-import GeoEco.ArcGIS
+from GeoEco.Metadata import *
-from GeoEco.Internationalization import _
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
-    
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        except Exception, e:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-# Private classes and functions global to this module
@@ -137 +227 @@
-            message = self.format(record)
-            if record.levelno >= logging.ERROR:
-tReal
+oprocessorManager.Get
-            elif record.levelno >= logging.WARNING:
-tReal
+oprocessorManager.Get
-            else:
-tReal
+oprocessorManager.Get
-        except:
-            self.handleError(record)
@@ -152 +242 @@
-    def Activate(cls):
-        if cls._PreactivationQueue is not None:
-tReal
-
+oprocessorManager.Get
+GeoprocessorManager.
-            while len(cls._PreactivationQueue) > 0:
-                record = cls._PreactivationQueue.pop(0)
@@ -163 +253 @@
-    _PreactivationQueue = []
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
-
-    def __init__(self):
@@ -260 +280 @@
-        else:
-            return None
+
-
-# Initialize, but do not activate, the ArcGIS logging handler. Until the handler
@@ -278 +299 @@
-except:
-    pass
+
+
+###############################################################################
+# Metadata: module
+###############################################################################
+
+AddModuleMetadata(shortDescription=_(u'Implements the Logger class, which other GeoEco classes use to report activity to the user.'))
+
+###############################################################################
+# Metadata: Logger class
+###############################################################################
+
+AddClassMetadata(Logger,
+    shortDescription=_(u'Provides methods for reporting messages to the user.'),
+    isExposedByIDispatch=True,
+    comIID=u'{0DA39145-CDE6-48F2-AFD9-8EA6623A3121}',
+    comCLSID=u'{EE5ED6B5-55E7-4D65-B627-EF062B8332C4}')
+
+# Public method: Debug
+
+AddMethodMetadata(Logger.Debug,
+    shortDescription=_(u'Reports a debugging message to the user.'),
+    longDescription=_(
+u"""Like the C printf function or the Python % operator, this method generates a
+message string by merging in the optional arguments into the format string.
+
+Debugging messages describe processing details that are usually not interesting
+unless the user is diagnosing a problem. The default configuration of the
+logging system causes debugging messages to be discarded."""),
+    isExposedByIDispatch=True)
+
+AddArgumentMetadata(Logger.Debug, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=Logger),
+    description=_(u'%s class or an instance of it.') % Logger.__name__)
+
+AddArgumentMetadata(Logger.Debug, u'format',
+    typeMetadata=PythonUnicodeString(),
+    description=_(
+u"""A printf-style format string. While Unicode strings are encouraged, this
+method will also accept an 8-bit string for this parameter. For a complete
+specification of the format of this string, look up "% formatting" in the Python
+documentation."""))
+
+AddArgumentMetadata(Logger.Debug, u'args',
+    typeMetadata=PythonTuple(elementType=AnyPythonInstance(canBeNone=True)),
+    description=_(u'Values to insert into the format string.'))
+
+# Public method: Info
+
+AddMethodMetadata(Logger.Info,
+    shortDescription=_(u'Reports an informational message to the user.'),
+    longDescription=_(
+u"""Like the C printf function or the Python % operator, this method generates a
+message string by merging in the optional arguments into the format string.
+
+Informational messages describe major processing steps that may be interesting to
+the user but do not require the user to take any action. For example, a method
+that performs three major processing tasks might report an informational message
+after each step is finished. Do not report too many informational messages or
+you may overwhelm the user. Report processing details as debug messages."""),
+    isExposedByIDispatch=True)
+
+AddArgumentMetadata(Logger.Info, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=Logger),
+    description=_(u'%s class or an instance of it.') % Logger.__name__)
+
+AddArgumentMetadata(Logger.Info, u'format',
+    typeMetadata=PythonUnicodeString(),
+    description=_(
+u"""A printf-style format string. While Unicode strings are encouraged, this
+method will also accept an 8-bit string for this parameter. For a complete
+specification of the format of this string, look up "% formatting" in the Python
+documentation."""))
+
+AddArgumentMetadata(Logger.Info, u'args',
+    typeMetadata=PythonTuple(elementType=AnyPythonInstance(canBeNone=True)),
+    description=_(u'Values to insert into the format string.'))
+
+# Public method: Warning
+
+AddMethodMetadata(Logger.Warning,
+    shortDescription=_(u'Reports a warning message to the user.'),
+    longDescription=_(
+u"""Like the C printf function or the Python % operator, this method generates a
+message string by merging in the optional arguments into the format string.
+
+Warning messages describe important events that should be brought to the user's
+attention but do not necessarily indicate that processing will fail."""),
+    isExposedByIDispatch=True)
+
+AddArgumentMetadata(Logger.Warning, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=Logger),
+    description=_(u'%s class or an instance of it.') % Logger.__name__)
+
+AddArgumentMetadata(Logger.Warning, u'format',
+    typeMetadata=PythonUnicodeString(),
+    description=_(
+u"""A printf-style format string. While Unicode strings are encouraged, this
+method will also accept an 8-bit string for this parameter. For a complete
+specification of the format of this string, look up "% formatting" in the Python
+documentation."""))
+
+AddArgumentMetadata(Logger.Warning, u'args',
+    typeMetadata=PythonTuple(elementType=AnyPythonInstance(canBeNone=True)),
+    description=_(u'Values to insert into the format string.'))
+
+# Public method: Error
+
+AddMethodMetadata(Logger.Error,
+    shortDescription=_(u'Reports an error message to the user.'),
+    longDescription=_(
+u"""Like the C printf function or the Python % operator, this method generates a
+message string by merging in the optional arguments into the format string.
+
+Error messages describe failures that halt processing and require the user to
+fix a problem and restart processing."""),
+    isExposedByIDispatch=True)
+
+AddArgumentMetadata(Logger.Error, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=Logger),
+    description=_(u'%s class or an instance of it.') % Logger.__name__)
+
+AddArgumentMetadata(Logger.Error, u'format',
+    typeMetadata=PythonUnicodeString(),
+    description=_(
+u"""A printf-style format string. While Unicode strings are encouraged, this
+method will also accept an 8-bit string for this parameter. For a complete
+specification of the format of this string, look up "% formatting" in the Python
+documentation."""))
+
+AddArgumentMetadata(Logger.Error, u'args',
+    typeMetadata=PythonTuple(elementType=AnyPythonInstance(canBeNone=True)),
+    description=_(u'Values to insert into the format string.'))
+
+# Public method: Initialize
+
+AddMethodMetadata(Logger.Initialize,
+    shortDescription=_(u'Initializes the logging system.'),
+    longDescription=_(
+u"""Like the C printf function or the Python % operator, this method generates a
+message string by merging in the optional arguments into the format string.
+
+Error messages describe failures that halt processing and require the user to
+fix a problem and restart processing."""),
+    isExposedByIDispatch=True)
+
+AddArgumentMetadata(Logger.Initialize, u'cls',
+    typeMetadata=PythonClassOrClassInstance(cls=Logger),
+    description=_(u'%s class or an instance of it.') % Logger.__name__)
+
+AddArgumentMetadata(Logger.Initialize, u'loggingConfigFile',
+    typeMetadata=PythonUnicodeString(canBeNone=True),
+    description=_(
+u"""Path to the logging configuration file. If not provided, the default logging
+configuration file will be used. The default file, Logging.txt, is located in
+the Configuration subdirectory of the GeoEco Python package subdirectory."""))
+
+AddArgumentMetadata(Logger.Initialize, u'activateArcGISLogging',
+    typeMetadata=PythonBoolean(canBeNone=True),
+    description=_(
+u"""If true, logging messages will be delivered to the ArcGIS geoprocessing
+system and appear in the ArcGIS user interface. If false, they will be reported
+to other logging destinations but will be queued in memory for ArcGIS until the
+ActivateArcGISLogging method is called. To limit memory consumption in the event
+that the method is never called, the queue retains only the most recent 1000
+messages. If you are calling Initialize but not running as part of an ArcGIS
+geoprocessing *do not* pass true for this parameter. Passing true will decrease
+performance by initializing the ArcGIS geoprocessor when it might not be
+necessary to do so. (The memory used by the queue is negligible.)"""))

MGET/Trunk/PythonPackage/src/GeoEco/Metadata.py

@@ -310 +310 @@
-    __doc__ = DynamicDocString()
-    
-
+, isExposedByIDispatch=False, comIID=None, comCLSID=None, comVersionIndependentProgID=None, comVersionDependentProgID=None
-
-        # If the caller did not provide a ModuleMetadata instance for the module
@@ -325 +325 @@
-        assert moduleMetadata.Object.__dict__.has_key(name) and inspect.isclass(moduleMetadata.Object.__dict__[name]), u'Module %s must contain a class named %s.' % (moduleMetadata.Name, name)
-        self._Module = moduleMetadata
+        self.IsExposedByIDispatch = isExposedByIDispatch
+        self.COMIID = comIID
+        self.COMCLSID = comCLSID
+        self.COMVersionIndependentProgID = comVersionIndependentProgID
+        self.COMVersionDependentProgID = comVersionDependentProgID
-
-    def _GetModule(self):
@@ -330 +335 @@
-    
-    Module = property(_GetModule, doc=DynamicDocString())
+
+    def _GetIsExposedByIDispatch(self):
+        return self._IsExposedByIDispatch
+    
+    def _SetIsExposedByIDispatch(self, value):
+        assert isinstance(value, types.BooleanType), u'IsExposedByIDispatch must be a %s.' % types.BooleanType.__name__
+        self._IsExposedByIDispatch = value
+        
+    IsExposedByIDispatch = property(_GetIsExposedByIDispatch, _SetIsExposedByIDispatch, doc=DynamicDocString())
+
+    def _GetCOMIID(self):
+        return self._COMIID
+    
+    def _SetCOMIID(self, value):
+        assert isinstance(value, (types.UnicodeType, types.NoneType)), u'COMIID must be a %s, or None.' % types.UnicodeType.__name__
+        if value is not None:
+            assert re.match(u'^\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\}$', value), u'COMIID must be a GUID, in string format (e.g. u\'{CB2E1BC5-D6A5-11D2-852D-204C4F4F5020}\').'
+        self._COMIID = value
+        
+    COMIID = property(_GetCOMIID, _SetCOMIID, doc=DynamicDocString())
+
+    def _GetCOMCLSID(self):
+        return self._COMCLSID
+    
+    def _SetCOMCLSID(self, value):
+        assert isinstance(value, (types.UnicodeType, types.NoneType)), u'COMCLSID must be a %s, or None.' % types.UnicodeType.__name__
+        if value is not None:
+            assert re.match(u'^\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\}$', value), u'COMCLSID must be a GUID, in string format (e.g. u\'{CB2E1BC5-D6A5-11D2-852D-204C4F4F5020}\').'
+        self._COMCLSID = value
+        
+    COMCLSID = property(_GetCOMCLSID, _SetCOMCLSID, doc=DynamicDocString())
+
+    def _GetCOMVersionIndependentProgID(self):
+        return self._COMVersionIndependentProgID
+    
+    def _SetCOMVersionIndependentProgID(self, value):
+        assert isinstance(value, (types.UnicodeType, types.NoneType)), u'COMVersionIndependentProgID must be a %s, or None.' % types.UnicodeType.__name__
+        if value is None:
+            self._COMVersionIndependentProgID = u'GeoEco.' + unicode(self.Name)
+        else:
+            self._COMVersionIndependentProgID = value
+        
+    COMVersionIndependentProgID = property(_GetCOMVersionIndependentProgID, _SetCOMVersionIndependentProgID, doc=DynamicDocString())
+
+    def _GetCOMVersionDependentProgID(self):
+        return self._COMVersionDependentProgID
+    
+    def _SetCOMVersionDependentProgID(self, value):
+        assert isinstance(value, (types.UnicodeType, types.NoneType)), u'COMVersionDependentProgID must be a %s, or None.' % types.UnicodeType.__name__
+        if value is None:
+            self._COMVersionDependentProgID = u'GeoEco.' + unicode(self.Name) + u'.1'
+        else:
+            self._COMVersionDependentProgID = value
+        
+    COMVersionDependentProgID = property(_GetCOMVersionDependentProgID, _SetCOMVersionDependentProgID, doc=DynamicDocString())
-
-    def _GetObject(self):
@@ -496 +556 @@
-        assert issubclass(cls, object), u'ValidatePropertyAssignment should only be called from the "fset" method of a property. By definition, only "new-style" classes (those that derive from object) can have properties.'
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        propName = None
-        prop = None
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        assert propName is not None and prop is not None, u'ValidatePropertyAssignment should only be called from the "fset" method of a property. None of the properties in class %s use method %s for their "fset" method. Please do not call ValidatePropertyAssignment from %s.' % (cls.__name__, method.__name__, method.__name__)
-
@@ -564 +675 @@
-    def AppendXMLNodes(self, node, document):
-        super(ClassMetadata, self).AppendXMLNodes(node, document)
+        self.AppendPropertyXMLNode(self, u'IsExposedByIDispatch', node, document)
+        self.AppendPropertyXMLNode(self, u'COMIID', node, document)
+        self.AppendPropertyXMLNode(self, u'COMCLSID', node, document)
+        self.AppendPropertyXMLNode(self, u'COMVersionIndependentProgID', node, document)
+        self.AppendPropertyXMLNode(self, u'COMVersionDependentProgID', node, document)
-        propertiesNode = node.appendChild(document.createElement(u'Properties'))
-        for (name, prop) in inspect.getmembers(self.Object, inspect.isdatadescriptor):
@@ -680 +796 @@
-        self.AppendPropertyXMLNode(self, u'IsExposedByPython', node, document)
-        self.AppendPropertyXMLNode(self, u'IsExposedByIDispatch', node, document)
+        self.AppendPropertyXMLNode(self, u'IsReadOnly', node, document)
-        
-    
@@ -883 +1000 @@
-        self._Method = methodMetadata
-        (args, varargs, varkw, defaults) = inspect.getargspec(methodMetadata.Object)
-varargs is not None and name == varargs or varkw is not None and name == varkw
+(varargs is not None and name == varargs or varkw is not None and name == varkw)
-        if not argFound:
-            for arg in args:
@@ -996 +1113 @@
-    def _GetHasDefault(self):
-        (args, varargs, varkw, defaults) = inspect.getargspec(self.Method.Object)
+        if self.Name == varargs or self.Name == varkw:
+            return False
-        for i in range(len(args)):
-            if args[i] == self.Name:
@@ -1007 +1126 @@
-    def _GetDefault(self):
-        (args, varargs, varkw, defaults) = inspect.getargspec(self.Method.Object)
+        if self.Name == varargs or self.Name == varkw:
+            return None
-        for i in range(len(args)):
-            if args[i] == self.Name:
@@ -1124 +1245 @@
-class TypeMetadata(object):
-
-
+comIDLType=None, canBeIDispatchParameter=False, 
-        assert isinstance(pythonType, (types.TypeType, types.ClassType)) and not issubclass(pythonType, types.NoneType), u'pythonType must be a type or old-style class, and it may not be types.NoneType or derived from it.'
-        assert isinstance(canBeNone, types.BooleanType), u'canBeNone must be a boolean.'
+        assert isinstance(comIDLType, (types.NoneType, types.UnicodeType)), u'comIDLType must be a unicode string, or None.'
+        assert isinstance(canBeIDispatchParameter, types.BooleanType), u'canBeIDispatchParameter must be a boolean.'
-        assert arcGISType is None and arcGISAssembly is None or isinstance(arcGISType, types.UnicodeType) and isinstance(arcGISAssembly, types.UnicodeType), u'arcGISType and arcGISAssembly must both be Unicode strings or both be None.'
-        assert isinstance(canBeArcGISInputParameter, types.BooleanType), u'canBeArcGISInputParameter must be a boolean.'
@@ -1132 +1255 @@
-        self._PythonType = pythonType
-        self._CanBeNone = canBeNone
+        self._COMIDLType = comIDLType
+        self._CanBeIDispatchParameter = canBeIDispatchParameter
-        self._ArcGISType = arcGISType
-        self._ArcGISAssembly = arcGISAssembly
@@ -1146 +1271 @@
-    
-    CanBeNone = property(_GetCanBeNone, doc=DynamicDocString())
+
+    def _GetCOMIDLType(self):
+        return self._COMIDLType
+    
+    COMIDLType = property(_GetCOMIDLType, doc=DynamicDocString())
+
+    def _GetCanBeIDispatchParameter(self):
+        return self._CanBeIDispatchParameter
+    
+    CanBeIDispatchParameter = property(_GetCanBeIDispatchParameter, doc=DynamicDocString())
-
-    def _GetArcGISType(self):
@@ -1178 +1313 @@
-        node.appendChild(document.createElement(u'PythonType')).appendChild(document.createTextNode(self.PythonType.__name__))
-        Metadata.AppendPropertyXMLNode(self, u'CanBeNone', node, document)
+        Metadata.AppendPropertyXMLNode(self, u'COMIDLType', node, document)
+        Metadata.AppendPropertyXMLNode(self, u'CanBeIDispatchParameter', node, document)
-        Metadata.AppendPropertyXMLNode(self, u'ArcGISType', node, document)
-        Metadata.AppendPropertyXMLNode(self, u'ArcGISAssembly', node, document)
@@ -1192 +1329 @@
-        elif not isinstance(value, self.PythonType):
-            raise TypeError(_(u'The value provided for the %s is invalid because it is a %s, an invalid type. Please provide a value of type %s.') % (variableName, type(value).__name__, self.PythonType.__name__))
+
+    def COMIDLRepresentationOfValue(self, value):
+        return None
-
-    def ParseValueFromArcGISInputParameterString(self, paramString, paramDisplayName, paramIndex):
@@ -1330 +1470 @@
-
-
-
+, isExposedByIDispatch=False, comIID=None, comCLSID=None, comVersionIndependentProgID=None, comVersionDependentProgID=None
-    module = _GetModuleObject(module)
-    assert isinstance(module.__doc__, DynamicDocString) and isinstance(module.__doc__.Obj, ModuleMetadata), u'The __doc__ attribute of module %s must be an instance of GeoEco.Metadata.DynamicDocString, and __doc__.Obj must be an instance of GeoEco.Metadata.ModuleMetadata. Use the GeoEco.Metadata.AddModuleMetadata function to add the module\'s metadata before calling GeoEco.Metadata.AddClassMetadata.' % module.__name__
-    cls = _GetClassObject(cls, module)
-s
+
-    assert cls.__doc__.Obj is None, u'%s.__doc__.Obj must be None. Do not call AddClassMetadata on a class that already has metadata.' % cls.__name__
-
+, isExposedByIDispatch, comIID, comCLSID, comVersionIndependentProgID, comVersionDependentProgID
-
-
@@ -1364 +1504 @@
-                        propName = attr
-        assert cls is not None, u'If prop is a property object and cls is None, module %s must contain the class to which prop belongs.' % module.__name__
-s
+
-    assert isinstance(cls.__doc__.Obj, ClassMetadata), u'%s.__doc__.Obj must be an instance of GeoEco.Metadata.ClassMetadata. Before calling GeoEco.Metadata.AddPropertyMetadata, use GeoEco.Metadata.AddClassMetadata to add ClassMetadata to class %s.' % (cls.__name__, cls.__name__)
-    assert isinstance(prop.__doc__, DynamicDocString), u'%s.%s.__doc__ must be an instance of GeoEco.Metadata.DynamicDocString. When defining the property, set the doc parameter to a new instance of DynamicDocString, like this:\n\n    %s = property(..., doc=DynamicDocString())' % (cls.__name__, propName, propName)
@@ -1667 +1807 @@
-    shortDescription=_(u'%s instance for the module that contains this class.') % ModuleMetadata.__name__)
-
+AddPropertyMetadata(ClassMetadata.IsExposedByIDispatch,
+    typeMetadata=PythonBoolean(),
+    shortDescription=_(u'True if this class is exposed using the Microsoft COM IDispatch interface on Windows operating systems.'),
+    longDescription=_(u'Components that expose an IDispatch interface are sometimes called COM Automation components or ActiveX components. Exposing the IDispatch interface allows the component to be invoked from virtually any programming language.'))
+
+AddPropertyMetadata(ClassMetadata.COMIID,
+    typeMetadata=PythonUnicodeString(),
+    shortDescription=_(u'Microsoft COM IID (interface ID) for the COM interface exposed by this class, in GUID string format (e.g. u\'{CB2E1BC5-D6A5-11D2-852D-204C4F4F5020}\').'),
+    longDescription=_(u'The IID is the globally-unique identifier for the COM interface that represents this class under the COM infrastructure. Windows programs invoke properties and methods of this class through COM using this indentifier.'),
+    devTeamNotes=_(
+u"""This property is only relevant if IsExposedByIDispatch is True. If you set
+IsExposedByIDispatch to True, you must supply a value for COMIID. You may
+obtain a random, globally-unique value like this::
+
+    >>> import pythoncom
+    >>> unicode(pythoncom.CreateGuid())
+    u'{890E7DF8-FC16-43BD-BF14-B08890F6CC0C}'
+"""))
+
+AddPropertyMetadata(ClassMetadata.COMCLSID,
+    typeMetadata=PythonUnicodeString(),
+    shortDescription=_(u'Microsoft COM CLSID (class ID) for this class, in GUID string format (e.g. u\'{CB2E1BC5-D6A5-11D2-852D-204C4F4F5020}\').'),
+    longDescription=_(u'The CLSID is the globally-unique identifier for this class under the COM infrastructure. Windows programs create instances of this class through COM using this indentifier.'),
+    devTeamNotes=_(
+u"""This property is only relevant if IsExposedByIDispatch is True. If you set
+IsExposedByIDispatch to True, you must supply a value for COMCLSID. You may
+obtain a random, globally-unique value like this::
+
+    >>> import pythoncom
+    >>> unicode(pythoncom.CreateGuid())
+    u'{890E7DF8-FC16-43BD-BF14-B08890F6CC0C}'
+"""))
+
+AddPropertyMetadata(ClassMetadata.COMVersionIndependentProgID,
+    typeMetadata=PythonUnicodeString(),
+    shortDescription=_(u'Microsoft COM "version-independent ProgID" for this class.'),
+    longDescription=_(
+u"""A ProgID is human-readable identifier for a class under the COM
+infrastructure, such as "'GeoEco.Tools.HelloWorld". Windows programs can
+create instances of this class through COM using the ProgID raster than the
+CLSID. Many programmers prefer to use the ProgID rather than the CLSID."""),
+    devTeamNotes=_(
+u"""The ProgID provides one level of indirection in component name resolution. When
+a program creates a component instance using the ProgID, COM looks up the CLSID
+from the ProgID and instantiates the component using the CLSID. This allows the
+component developer to change the component's CLSID while leaving the ProgID
+unchanged. The calling programs will automatically create the new component
+without any code changes.
+
+A further level of indirection is allowed by the provision of both version-
+independent and version-dependent ProgIDs. Traditionally, a component provides
+a single version-independent ProgID, such as "GeoEco.Tools.HelloWorld" and
+one or more version-dependent ProgIDs, such as
+"GeoEco.Tools.HelloWorld.HelloWorld.1", "GeoEco.Tools.HelloWorld.HelloWorld.2"
+and "GeoEco.Tools.HelloWorld.HelloWorld.3". The version-independent ProgID
+resolves to the latest version-dependent ProgID,
+"GeoEco.Tools.HelloWorld.HelloWorld.3" in this case. Programs instantiate the
+version-independent ID if they always want the latest version of the component,
+or a version-dependent ID if they want a specific version. Multiple versions of
+the component may be installed simultaneously, if the component supports it.
+
+GeoEco does not support multiple simultaneous installations. A program that
+instantiates a GeoEco class by ProgID may use either of two strategies:
+
+* Use the version-independent ProgID. This will guarantee that the program will
+  obtain an instance no matter what version of GeoEco is installed, but the
+  program must handle any behavior changes between component versions.
+
+* Use the version-dependent ProgIDs. This will guarantee that the program will
+  only obtain an instance of a specific version. The program will not need to
+  deal with behavior differences between versions, but instantiation will fail
+  if the requested version is not installed.
+
+To facilitate these strategies, the following approach is recommended for
+developers of GeoEco classes that will be exposed through COM.
+
+* Do not specify a COMVersionIndependentProgID for your ClassMetadata. By
+  default, your class's version-independent ProgID will be "GeoEco." plus the
+  class name, e.g. "GeoEco.HelloWorld". This scheme means that your class's name
+  must be unique across all GeoEco classes exposed by COM, regardless of what
+  modules they are defined in. You cannot use submodules and subpackages to
+  disambiguate classes with the same name. (This restriction is cumbersome
+  but it allows the ProgIDs to remain consistent with the type information
+  exposed to early-bound callers by the GeoEco type library. Please contact the
+  author of GeoEco's COM infrastructure for a full explanation.)
+
+* For the first version of your class, do not specify a COMVersionDependentProgID.
+  By default, your class's version dependent ProgID will by the module name plus
+  the class name plus ".1", e.g. "GeoEco.HelloWorld.1".
+
+* If your component ever changes its behavior "significantly" between GeoEco
+  versions, specify a new version-dependent ProgID that is "one number higher"
+  than the previous one, e.g. "GeoEco.HelloWorld.2" for the second version. It
+  is up to you what "significantly" means. One possible definition of a
+  "signficant" change is one that would cause a double-digit percentage of your
+  callers to fail or receive bad results if they blindly invoked the new version.
+  (Callers that invoke using the version-independent ProgID will still break,
+  but they incurred that risk when they chose to bind to that ProgID, rather
+  than the version-dependent one.)
+"""))
+
+AddPropertyMetadata(ClassMetadata.COMVersionDependentProgID,
+    typeMetadata=PythonUnicodeString(),
+    shortDescription=_(u'Microsoft COM "version-dependent ProgID" for this class.'),
+    longDescription=ClassMetadata.COMVersionIndependentProgID.__doc__.Obj.LongDescription,
+    devTeamNotes=ClassMetadata.COMVersionIndependentProgID.__doc__.Obj.DevTeamNotes)
+
-# Public method: ValidatePropertyAssignment
-

MGET/Trunk/PythonPackage/src/GeoEco/Tools/HelloWorld.py

@@ -4 +4 @@
-from GeoEco.Logging import *
-from GeoEco.Metadata import *
-from GeoEco.Tool import *
-from GeoEco.Types import *
-
-Tool
+object
-    __doc__ = DynamicDocString()
-
+    _public_methods_ = ['GreetPerson']
+    
-    @classmethod
-    def GreetPerson(cls, person=_(u'World')):
-        cls.__doc__.Obj.ValidateMethodInvocation()
-        greeting = _(u'Hello %s!') % person.strip()
-
+ger.
-        return greeting
-    
@@ -25 +26 @@
-            greeting = _(u'Hello %s!') % people[0]
-        else:
-
-
+ger.
+ger.
-        return greeting
-
-    @classmethod
-    def TestParameterTypes(cls, oneBoolean=True, listOfBooleans=[False,True,False], oneFloat=1.0, listOfFloats=[2.0, 3.0, 4.0], oneInt=5, listOfInts=[5,6,7], oneString=u'Foo', listOfStrings=[u'Blah',u'Blah',u'Blah']):
-
-
-
-
-
-
-
-
+ger.
+ger.
+ger.
+ger.
+ger.
+ger.
+ger.
+ger.
-        return oneBoolean, oneFloat, oneInt, oneString
-
@@ -46 +47 @@
-###############################################################################
-
-tool
+class exposed to external callers
-
-###############################################################################
@@ -53 +54 @@
-
-AddClassMetadata(HelloWorld,
-tool
+class exposed to external callers
-    longDescription=
-_(u"""At the beginning of their classic text on the C programming language, Brian
@@ -61 +62 @@
-authors have introduced new programming languages. In the spririt of this
-tradition, I have provided a HelloWorld class to illustrate, as succinctly as
-
+
+
+
+
-
-# Public method: GreetPerson
@@ -67 +71 @@
-AddMethodMetadata(HelloWorld.GreetPerson,
-    shortDescription=_(u'Greets a specified person.'),
+    isExposedByIDispatch=True,
-    isExposedAsArcGISTool=True,
-    arcGISDisplayName=_(u'Greet Person'),
-    arcGISToolCategory=_(u'Examples'))
-
-
+#
-
-AddArgumentMetadata(HelloWorld.GreetPerson, u'cls',
@@ -78 +83 @@
-
-AddArgumentMetadata(HelloWorld.GreetPerson, u'person',
-
+canBeNone=True
-    description=_(u'Person to greet.'),
-    arcGISDisplayName=_(u'Person to Greet'))

MGET/Trunk/PythonPackage/src/GeoEco/Types.py

@@ -8 +8 @@
-
-
-
+
+
+
+
+
+
+
-
-
@@ -32 +38 @@
-
-
+# Simple Python types from which many other types derive:
+
+
-class PythonBoolean(TypeMetadata):
-
-    def __init__(self, canBeNone=False):
-
+comIDLType=u'VARIANT_BOOL', canBeIDispatchParameter=True, 
-
-    def AppendXMLNodesForValue(self, value, node, document):
@@ -42 +51 @@
-        assert isinstance(document, xml.dom.Node) and document.nodeType == xml.dom.Node.DOCUMENT_NODE, u'node must be an instance of xml.dom.Node with nodeType==DOCUMENT_NODE'
-        node.appendChild(document.createElement(u'boolean')).appendChild(document.createTextNode(unicode(value).lower()))
+
+    def COMIDLRepresentationOfValue(self, value):
+        assert isinstance(value, types.BooleanType), u'value must be a boolean'
+        if value:
+            return 'VARIANT_TRUE'
+        return 'VARIANT_FALSE'
-
-    def ParseValueFromArcGISInputParameterString(self, paramString, paramDisplayName, paramIndex):
@@ -55 +70 @@
-
-    def __init__(self, canBeNone=False):
-
+comIDLType=u'double', canBeIDispatchParameter=True, 
-
-    def AppendXMLNodesForValue(self, value, node, document):
@@ -62 +77 @@
-        assert isinstance(document, xml.dom.Node) and document.nodeType == xml.dom.Node.DOCUMENT_NODE, u'node must be an instance of xml.dom.Node with nodeType==DOCUMENT_NODE'
-        node.appendChild(document.createElement(u'double')).appendChild(document.createTextNode(unicode(value)))
+
+    def COMIDLRepresentationOfValue(self, value):
+        assert isinstance(value, types.FloatType), u'value must be a float'
+        return str(value)
-
-    def ParseValueFromArcGISInputParameterString(self, paramString, paramDisplayName, paramIndex):
@@ -75 +94 @@
-
-    def __init__(self, canBeNone=False):
-
+comIDLType=u'long', canBeIDispatchParameter=True, 
-
-    def AppendXMLNodesForValue(self, value, node, document):
@@ -82 +101 @@
-        assert isinstance(document, xml.dom.Node) and document.nodeType == xml.dom.Node.DOCUMENT_NODE, u'node must be an instance of xml.dom.Node with nodeType==DOCUMENT_NODE'
-        node.appendChild(document.createElement(u'int')).appendChild(document.createTextNode(unicode(value)))
+
+    def COMIDLRepresentationOfValue(self, value):
+        assert isinstance(value, types.IntType), u'value must be an int'
+        return str(value)
-
-    def ParseValueFromArcGISInputParameterString(self, paramString, paramDisplayName, paramIndex):
@@ -95 +118 @@
-
-    def __init__(self, canBeNone=False):
-
+
+
+
+
+
-
-    def AppendXMLNodesForValue(self, value, node, document):
@@ -104 +131 @@
-
-
-
-
-
+
+
+
+
+
+
-        assert isinstance(elementType, TypeMetadata), u'elementType must be an instance of TypeMetadata'
-
+
+
-        self._ElementType = elementType
-
@@ -117 +148 @@
-
-    def AppendXMLNodes(self, node, document):
-List
+Sequence
-        elementTypeNode = node.appendChild(document.createElement(u'ElementTypeMetadata'))
-        self.ElementType.AppendXMLNodes(elementTypeNode, document)
@@ -130 +161 @@
-
-    def ValidateValue(self, value, variableName):
-
+
+
+
-        for i in range(len(value)):
-            self.ElementType.ValidateValue(value[i], _(u'element %i of the %s (where 0 is the first element)'))
-
-    def ParseValueFromArcGISInputParameterString(self, paramString, paramDisplayName, paramIndex):
-List
+Sequence
-
-        # The input string is a list of values formatted as follows:
@@ -161 +194 @@
-        while i < len(paramString):
-
-
-
+ger.
+ger.
-            
-            if state == FIRST_CHARACTER:
@@ -213 +246 @@
-                raise RuntimeError(_(u'Failed to parse a list of values from the string provided for the %s parameter (parameter number %i) due to a programming error in the parser: the parser was found to be in unknown state %i. Please contact the author of this tool for assistance.') % (paramDisplayName, paramIndex, state))
-
-
+ger.
-
-            i += 1
@@ -249 +282 @@
-                
-        return values
+
+
+class PythonList(PythonSequence):
+
+    def __init__(self, elementType, canBeNone=False):
+        super(PythonList, self).__init__(elementType=elementType, pythonType=types.ListType, canBeNone=canBeNone)
+
+
+class PythonTuple(PythonSequence):
+
+    def __init__(self, elementType, canBeNone=False):
+        super(PythonTuple, self).__init__(elementType=elementType, pythonType=types.TupleType, canBeNone=canBeNone)
+
+    def ParseValueFromArcGISInputParameterString(self, paramString, paramDisplayName, paramIndex):
+        resultList = super(PythonTuple, self).ParseValueFromArcGISInputParameterString(paramString, paramDisplayName, paramIndex)
+        return tuple(resultList)

MGET/Trunk/VisualStudioSolutions/CreateArcGISToolbox/Program.cs

@@ -46 +46 @@
-        #region Fields deserialized from Metadata.xml
-
+        public bool IsExposedByIDispatch;
+        public string COMIID;
+        public string COMCLSID;
+        public string COMVersionIndependentProgID;
+        public string COMVersionDependentProgID;
-        public PropertyMetadata[] Properties;
-        public MethodMetadata[] Methods;
@@ -57 +62 @@
-
-        [XmlElement(typeof(TypeMetadata)),
+        XmlElement(typeof(AnyPythonInstance)),
-        XmlElement(typeof(PythonClassInstance)),
-        XmlElement(typeof(PythonClassOrClassInstance)),
@@ -63 +69 @@
-        XmlElement(typeof(PythonInteger)),
-        XmlElement(typeof(PythonUnicodeString)),
-
+
+
+
-        public TypeMetadata TypeMetadata;
-        public bool IsExposedByPython;
-        public bool IsExposedByIDispatch;
+        public bool IsReadOnly;
-
-        #endregion
@@ -95 +104 @@
-        public string Name;
-        [XmlElement(typeof(TypeMetadata)),
+        XmlElement(typeof(AnyPythonInstance)),
-        XmlElement(typeof(PythonClassInstance)),
-        XmlElement(typeof(PythonClassOrClassInstance)),
@@ -101 +111 @@
-        XmlElement(typeof(PythonInteger)),
-        XmlElement(typeof(PythonUnicodeString)),
-
+
+
+
-        public TypeMetadata TypeMetadata;
-        [XmlAnyElement(Name = "Description")]
@@ -127 +139 @@
-        public string Name;
-        [XmlElement(typeof(TypeMetadata)),
+        XmlElement(typeof(AnyPythonInstance)),
-        XmlElement(typeof(PythonClassInstance)),
-        XmlElement(typeof(PythonClassOrClassInstance)),
@@ -133 +146 @@
-        XmlElement(typeof(PythonInteger)),
-        XmlElement(typeof(PythonUnicodeString)),
-
+
+
+
-        public TypeMetadata TypeMetadata;
-        [XmlAnyElement(Name = "Description")]
@@ -150 +165 @@
-        public string PythonType;
-        public bool CanBeNone;
+        public string COMIDLType;
+        public bool CanBeIDispatchParameter;
+        public string ArcGISType;
+        public string ArcGISAssembly;
-        public bool CanBeArcGISInputParameter;
-        public bool CanBeArcGISOutputParameter;
-        public string ArcGISType;
-        public string ArcGISAssembly;
-
-        #endregion
@@ -214 +231 @@
-    }
-
-PythonClassOrClass
+AnyPython
-    {
-        #region Overridden TypeMetadata members
@@ -228 +245 @@
-    }
-
+    public class PythonClassOrClassInstance : TypeMetadata
+    {
+        #region Overridden TypeMetadata members
+
+        public override System.Type DotNetType { get { throw new NotSupportedException(); } }
+        public override string NameForSerializedXmlValue { get { throw new NotSupportedException(); } }
+        public override object DeserializeValueFromXmlElement(XmlElement element) { throw new NotSupportedException(); }
+        public override IGPDataType GetIGPDataTypeInstance() { throw new NotSupportedException(); }
+        public override IGPValue GetIGPValueInstance(object value) { throw new NotSupportedException(); }
+        public override IGPValue GetIGPValueInstanceForDerivedOutput(Result result) { throw new NotSupportedException(); }
+
+        #endregion
+    }
+
-    public class PythonBoolean : TypeMetadata
-    {
@@ -275 +306 @@
-    }
-
-List
+Sequence
-    {
-        #region Fields deserialized from Metadata.xml
-
-        [XmlElement("ElementTypeMetadata", typeof(TypeMetadata)),
+        XmlElement(typeof(AnyPythonInstance)),
-        XmlElement(typeof(PythonClassInstance)),
-        XmlElement(typeof(PythonClassOrClassInstance)),
@@ -286 +318 @@
-        XmlElement(typeof(PythonInteger)),
-        XmlElement(typeof(PythonUnicodeString)),
-
+
+
+
-        public TypeMetadata ElementTypeMetadata;
-
@@ -342 +376 @@
-        #endregion
-    }
+
+    public class PythonList : PythonSequence { }
+
+    public class PythonTuple : PythonSequence { }
-
-    class Program