Merge pull request #20 from UdK-VPT/v1.0_docs_examples

V1.0 docs examples

CoTeTo/Loaders/CSVFile.py

@@ -20,7 +20,7 @@ def load(self, uriList):
         for u in uriList:
             if isfile(u):
                 self.logger.info('CSVFile - loading %s', u)
-                with open(u, r) as f:
+                with open(u, 'r') as f:
                     dialect = Sniffer().sniff(f.read(1024))
                     f.seek(0)
                     data[u] = DictReader(f, dialect)

CoTeTo/Loaders/JSONFile.py

@@ -20,7 +20,8 @@ def load(self, uriList):
         for u in uriList:
             if isfile(u):
                 self.logger.info('JSONFile - loading %s', u)
-                data[u] = load(open(u, 'r'))
+                with open(u, 'r') as f:
+                    data[u] = load(f)
             else:
                 data[u] = None
                 self.logger.error('JSONFile - file not readable %s', u)

CoTeTo/Loaders/PickleFile.py

@@ -20,7 +20,8 @@ def load(self, uriList):
         for u in uriList:
             if isfile(u):
                 self.logger.info('PickleFile - loading %s', u)
-                data[u] = load(open(u, 'r'))
+                with open(u, 'r') as f:
+                    data[u] = load(f)
             else:
                 data[u] = None
                 self.logger.error('PickleFile - file not readable %s', u)

CoTeTo/__init__.py

@@ -6,9 +6,10 @@
 
 import sys
 
-__version__ = '0.99'
+__version__ = '1.0'
 
 # special hack for mako on windows to correct a nasty line ending problem
+# FIXME: is this still needed?
 if sys.platform.startswith('win'):
     def read_file(path, mode='r'):
         fp = open(path, mode)

Generators/TestMako/Filters/Filter01.py → Generators/Example01Mako/Filters/MyFilter.py

@@ -5,10 +5,10 @@
 #   logger - a logger instance
 
 
-def filter01(d, systemCfg, generatorCfg, logger):
+def myfilter(d, systemCfg, generatorCfg, logger):
 
     # spread a message
-    logger.debug('hi there! This is a filter running from module: ' + __file__)
+    logger.debug('Hi there! This is a filter running from module: ' + __file__)
 
     x = d['dummy']
 

Generators/Example01Mako/Package.inf

@@ -0,0 +1,40 @@
+# This is the main control file of a generator.
+# It follows the syntax defined by pythons configparser module.
+# More information: https://docs.python.org/3/library/configparser.html
+
+# The GENERATOR section defines the main attributes of this generator.
+# The combination of name and version must be unique in your generator path.
+[GENERATOR]
+name = Example01Mako
+version = 1.0
+description = Example using the default mako engine
+author = Joerg Raedler [email protected]
+
+# The LOADER section defines the used loader name and version.
+# This loader must exist in the CoTeTo.Loaders package or must be included
+# in the generator (see ExampleCustomLoader).
+# This example just uses a dummy loader that generates some useless data items and does not need any input!
+[LOADER]
+name = TestDummy
+minVer = 0.1
+maxVer = 2.0
+
+# The optional FILTER section defines a module and function to manipulate the 
+# data received from the loader before it is ued in the templates.
+[FILTER]
+module = MyFilter
+function = myfilter
+
+# The TEMPLATE section defines the file name of the main template.
+# mako is the default engine, but you can use jinja2 instead.
+# To output more than one file you can use multiple sections with different names,
+# see ExampleMultiOutput for details.
+[TEMPLATE]
+topFile = Main.mako
+type = mako
+
+# All other sections and entries will be ignored by the CoTeTo system, but you can
+# store information here which is available in custom loaders, filters and templates.
+# See ExampleCustomEntries for details.
+[MYCUSTOMSETTINGS]
+answer = 42

Generators/Example01Mako/Templates/Main.mako

@@ -0,0 +1,39 @@
+#
+#  The following objects can be used in templates: 
+#
+#  systemCfg - dictionary with information on the system and the environment
+#    Keys:          ${' '.join(systemCfg.keys())}
+#    CoTeToVersion: ${systemCfg['version']}
+#    CoTeToPath:    ${systemCfg['path']}
+#    Platform:      ${systemCfg['platform']}
+#    FullPlatform:  ${systemCfg['fullplatform']}
+#    Hostname:      ${systemCfg['hostname']}
+#    Username:      ${systemCfg['username']}
+#    GeneratorPath: ${', '.join(systemCfg['generatorPath'])}
+#
+#    the following are functions and need to be executed: 
+#    Timestamp:     ${systemCfg['timestamp']()}
+#    Infostamp:     ${systemCfg['infostamp']()}
+#
+#  generatorCfg - configparser object with information on the used generator
+#    (this is basically the contents of the Package.inf file)
+#    Sections:      ${' '.join(generatorCfg.keys())}
+#    Name:          ${generatorCfg['GENERATOR'].get('name')}
+#    Version:       ${generatorCfg['GENERATOR'].get('version')}
+#
+#    access to custom sections and values is also possible:
+#    Answer:        ${generatorCfg['MYCUSTOMSETTINGS'].getint('answer')}
+#
+#  logger - an object to send logging messages
+#    this will output None, but log a message: ${logger.info('The answer is 42!')}
+#    suppress the output with this trick: ${logger.warning('But what was the question?') or ''}
+#
+#  d - the data object read from the loader and (optionally) manipulated by the filter
+#    (this is usually a dictionary of the form filename : data_items, 
+#     but this depends on the loader and filter code)  
+#    Keys (Filenames/URIs):    ${' '.join(d.keys())}
+
+The value of foo is ${d['dummy']['foo']}. Please notice this value was manipulated by a filter function.
+
+## Templates can be splitted and included:
+<%include file="Sub.mako"/>

Generators/TestMako/Templates/Sub.mako → Generators/Example01Mako/Templates/Sub.mako

@@ -1,2 +1,2 @@
 Hello, I'm a sub template!
-bar = ${d['dummy']['bar']}
+bar = ${d['dummy']['bar']}

Generators/TestJinja2/Filters/Filter01.py → Generators/Example02Jinja2/Filters/MyFilter.py

@@ -5,10 +5,10 @@
 #   logger - a logger instance
 
 
-def filter01(d, systemCfg, generatorCfg, logger):
+def myfilter(d, systemCfg, generatorCfg, logger):
 
     # spread a message
-    logger.debug('hi there! This is a filter running from module: ' + __file__)
+    logger.debug('Hi there! This is a filter running from module: ' + __file__)
 
     x = d['dummy']
 

Generators/Example02Jinja2/Package.inf

@@ -0,0 +1,40 @@
+# This is the main control file of a generator.
+# It follows the syntax defined by pythons configparser module.
+# More information: https://docs.python.org/3/library/configparser.html
+
+# The GENERATOR section defines the main attributes of this generator.
+# The combination of name and version must be unique in your generator path.
+[GENERATOR]
+name = Example02Jinja2
+version = 1.0
+description = Example using the alternative jinja2 engine
+author = Joerg Raedler [email protected]
+
+# The LOADER section defines the used loader name and version.
+# This loader must exist in the CoTeTo.Loaders package or must be included
+# in the generator (see ExampleCustomLoader).
+# This example just uses a dummy loader that generates some useless data items and does not need any input!
+[LOADER]
+name = TestDummy
+minVer = 0.1
+maxVer = 2.0
+
+# The optional FILTER section defines a module and function to manipulate the 
+# data received from the loader before it is ued in the templates.
+[FILTER]
+module = MyFilter
+function = myfilter
+
+# The TEMPLATE section defines the file name of the main template.
+# mako is the default engine, but you can use jinja2 instead.
+# To output more than one file you can use multiple sections with different names,
+# see ExampleMultiOutput for details.
+[TEMPLATE]
+topFile = Main.jinja2
+type = jinja2
+
+# All other sections and entries will be ignored by the CoTeTo system, but you can
+# store information here which is available in custom loaders, filters and templates.
+# See ExampleCustomEntries for details.
+[MYCUSTOMSETTINGS]
+answer = 42

Generators/Example02Jinja2/Templates/Main.jinja2

@@ -0,0 +1,39 @@
+#
+#  The following objects can be used in templates: 
+#
+#  systemCfg - dictionary with information on the system and the environment
+#    Keys:          {{' '.join(systemCfg.keys())}}
+#    CoTeToVersion: {{systemCfg['version']}}
+#    CoTeToPath:    {{systemCfg['path']}}
+#    Platform:      {{systemCfg['platform']}}
+#    FullPlatform:  {{systemCfg['fullplatform']}}
+#    Hostname:      {{systemCfg['hostname']}}
+#    Username:      {{systemCfg['username']}}
+#    GeneratorPath: {{', '.join(systemCfg['generatorPath'])}}
+#
+#    the following are functions and need to be executed: 
+#    Timestamp:     {{systemCfg['timestamp']()}}
+#    Infostamp:     {{systemCfg['infostamp']()}}
+#
+#  generatorCfg - configparser object with information on the used generator
+#    (this is basically the contents of the Package.inf file)
+#    Sections:      {{' '.join(generatorCfg.keys())}}
+#    Name:          {{generatorCfg['GENERATOR'].get('name')}}
+#    Version:       {{generatorCfg['GENERATOR'].get('version')}}
+#
+#    access to custom sections and values is also possible:
+#    Answer:        {{generatorCfg['MYCUSTOMSETTINGS'].getint('answer')}}
+#
+#  logger - an object to send logging messages
+#    this will output None, but log a message: {{logger.info('The answer is 42!')}}
+#    suppress the output with this trick: {{logger.warning('But what was the question?') or ''}}
+#
+#  d - the data object read from the loader and (optionally) manipulated by the filter
+#    (this is usually a dictionary of the form filename : data_items, 
+#     but this depends on the loader and filter code)  
+#    Keys (Filenames/URIs):    {{' '.join(d.keys())}}
+
+The value of foo is {{d['dummy']['foo']}}. Please notice this value was manipulated by a filter function.
+
+## Templates can be splitted and included:
+{% include 'Sub.jinja2' %}

Generators/Example03CustomEntries/Package.inf

@@ -0,0 +1,18 @@
+[GENERATOR]
+name = Example03CustomEntries
+version = 1.0
+description = show the usage of custom entries in Package.inf
+author = Joerg Raedler [email protected]
+
+# You can add custom sections and entries and use the values in the loader, filter and templates.
+# Everything in this file is available as generatorCfg.
+[FOO_BAR]
+say_hello = 1
+
+[LOADER]
+name = TestDummy
+minVer = 0.1
+maxVer = 2.0
+
+[TEMPLATE]
+topFile = Main.tmpl

Generators/TestCustomEntries/Templates/Main.tmpl → Generators/Example03CustomEntries/Templates/Main.tmpl

@@ -1,13 +1,4 @@
-#
-#   CoTeTo
-#       Info:     ${systemCfg['infostamp']()}
-#       Path:     ${systemCfg['path']}
-#       Gen-Path: ${', '.join(systemCfg['generatorPath'])}
-#
-#   Generator
-#       Name:     ${generatorCfg['GENERATOR'].get('name')}
-#       Version:  ${generatorCfg['GENERATOR'].get('version')}
-
+#  ${systemCfg['infostamp']()}
 % if generatorCfg['FOO_BAR'].getboolean('say_hello'):
 Hello!
 Try to change the custom value in Package.inf, reload the generator and run again!

Generators/Example04MultiOutput/Package.inf

@@ -0,0 +1,24 @@
+[GENERATOR]
+name = Example04MultiOutput
+version = 1.0
+description = Output the lines of the input text files with line numbers added, generate a second file with some statistics
+author = Joerg Raedler [email protected]
+
+[LOADER]
+name = TextFile
+minVer = 0.1
+maxVer = 2.0
+
+# Any section name that starts with the string TEMPLATE can be used.
+# All template sections are executed in alphabetical order.
+# The extension ext will be appended to the output file or folder name.
+
+[TEMPLATE_NUMB]
+topFile = numberlines.tmpl
+type = mako
+ext = .numbered
+
+[TEMPLATE_STAT]
+topFile = statistics.tmpl
+type = mako
+ext = .statistics

Generators/Example05CustomLoaders/Package.inf

@@ -0,0 +1,18 @@
+[GENERATOR]
+name = Example05CustomLoaders
+version = 1.0
+description = test custom loaders - please load test/custom.txt as input
+author = Joerg Raedler [email protected]
+
+# A set of standard loaders is available in the package CoTeTo.Loaders,
+# but you can include your custom loader code in a generator. If the a value
+# for module is set in the LOADER section, CoTeTo will look for the module in
+# the Loaders folder of the generator. 
+[LOADER]
+name = MyLoader
+module = MyLoader
+minVer = 0.1
+maxVer = 2.0
+
+[TEMPLATE]
+topFile = Main.tmpl

Generators/Example06PostExec/Package.inf

@@ -0,0 +1,24 @@
+[GENERATOR]
+name = Example06PostExec
+version = 1.0
+description = Example of the post execution feature
+author = Joerg Raedler [email protected]
+
+[LOADER]
+name = TestDummy
+minVer = 0.1
+maxVer = 2.0
+
+[MYCUSTOMSETTINGS]
+answer = 42
+
+# If a value for postExec is defined in a TEMPLATE section, the python command is executed 
+# right after the creation of the file. The variable fname contains the name of the 
+# generated file. This feature can be used to run a compiler on generated code or start 
+# other applications to process/copy/upload the generated file.
+# Be VERY carefull with the postexec feature, it has complete access
+# to the whole namespace and will run this code without checking!
+[TEMPLATE]
+topFile = Main.mako
+type = mako
+postExec = os.system("dir "+fname)

Generators/Example06PostExec/Templates/Main.mako

@@ -0,0 +1,36 @@
+#
+#  The following objects can be used in templates: 
+#
+#  systemCfg - dictionary with information on the system and the environment
+#    Keys:          ${' '.join(systemCfg.keys())}
+#    CoTeToVersion: ${systemCfg['version']}
+#    CoTeToPath:    ${systemCfg['path']}
+#    Platform:      ${systemCfg['platform']}
+#    FullPlatform:  ${systemCfg['fullplatform']}
+#    Hostname:      ${systemCfg['hostname']}
+#    Username:      ${systemCfg['username']}
+#    GeneratorPath: ${', '.join(systemCfg['generatorPath'])}
+#
+#    the following are functions and need to be executed: 
+#    Timestamp:     ${systemCfg['timestamp']()}
+#    Infostamp:     ${systemCfg['infostamp']()}
+#
+#  generatorCfg - configparser object with information on the used generator
+#    (this is basically the contents of the Package.inf file)
+#    Sections:      ${' '.join(generatorCfg.keys())}
+#    Name:          ${generatorCfg['GENERATOR'].get('name')}
+#    Version:       ${generatorCfg['GENERATOR'].get('version')}
+#
+#    access to custom sections and values is also possible:
+#    Answer:        ${generatorCfg['MYCUSTOMSETTINGS'].getint('answer')}
+#
+#  logger - an object to send logging messages
+#    this will output None, but log a message: ${logger.info('The answer is 42!')}
+#    suppress the output with this trick: ${logger.warning('But what was the question?') or ''}
+#
+#  d - the data object read from the loader and (optionally) manipulated by the filter
+#    (this is usually a dictionary of the form filename : data_items, 
+#     but this depends on the loader and filter code)  
+#    Keys (Filenames/URIs):    ${' '.join(d.keys())}
+
+The value of foo is ${d['dummy']['foo']}.

Generators/Example07NumberLines/Package.inf

@@ -0,0 +1,14 @@
+[GENERATOR]
+name = Example07NumberLines
+version = 1.0
+description = Output the lines of the input text files with line numbers added
+author = Joerg Raedler [email protected]
+
+[LOADER]
+name = TextFile
+minVer = 0.1
+maxVer = 2.0
+
+[TEMPLATES]
+topFile = numberlines.mao
+type = mako

Generators/JsonFluid/Package.inf → Generators/Example50JsonFluid/Package.inf

@@ -1,6 +1,6 @@
 [GENERATOR]
-name = JsonFluid
-version = 0.1
+name = Example50JsonFluid
+version = 1.0
 description = Reads information about Equations of States for fluids from CoolProp json file and generates HelmholtzMedia Modelica input files.
 author = Matthis Thorade