[debug] add --exit-on-error and --debug flags. (0.0.13)

* add TROUBLESHOOTING
* update README and EXAMPLES

README.md

@@ -142,6 +142,10 @@ plait.py also simplifies looking up faker fields:
 * see docs/EXAMPLES.md
 * also see templates/ dir
 
+### troubleshooting
+
+* see docs/TROUBLESHOOTING.md
+
 ### future direction
 
 Currently, plait.py models independent markov processes - future investigation

docs/EXAMPLES.md

@@ -136,3 +136,54 @@
         column: 2
         index: 3
         lookup: this.zipcode
+
+### using custom imports
+
+    fields:
+      _geoip:
+        lambda: geoip.geolite2.lookup(this.ip)
+
+      ip:
+        template: web/ip.yaml
+
+      country:
+        onlyif: this._geoip and this._geoip.country
+        lambda: this._geoip.country
+
+    imports:
+      - geoip
+
+    requirements:
+      - python-geoip
+      - python-geoip-geolite2
+
+If a template fails an import, the **requirements** field will be printed to
+the console, letting the caller know which packages might be required for the
+template to work.
+
+
+## using a custom printer
+
+    define:
+      N: int(100)
+      K: int(100)
+
+    fields:
+      n:
+        random: randint(0, ${N})
+      k:
+        random: randint(0, ${K})
+      arr:
+        random: |
+          [ randint(0, this.k) for _ in range(this.n) ]
+
+
+    printer: |
+      print(this.n, this.k)
+      print(*this.arr, sep=" ")
+
+notice that the `|` character in yaml is a multi-line comment separated by
+newlines. this is really useful for defining multi-line functions. if the `>`
+character was used instead, the **printer:** would not work, because `>` is a
+comment separated by spaces in YAML and the resulting string would be invalid
+code.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,37 @@
+## debugging
+
+debug output can be sent to stderr by using the `--debug` flag or by setting
+`DEBUG=1` as an environment variable.
+
+adding `--exit-on-error` will cause plait.py to end early when errors occur
+during field generation.
+
+### static field is missing or misdefined
+
+To see how the static fields are setup in a template, turn on debugging and
+redirect stdout to /dev/null. The command output will show what the definition
+for each static variable is.
+
+### template returns None
+
+If a template is not returning any results (f.e. [this
+issue](https://github.com/plaitpy/plaitpy/issues/3), turn on debugging
+to get more details. If that doesn't work, open an issue.
+
+## misc
+
+### using custom imports
+
+Remember to add the `imports` field to your template with the module that is
+being imported, like so:
+
+    fields:
+      foo:
+        lambda: datetime.datetime()
+
+    imports:
+      - datetime
+
+## still having trouble?
+
+please open an issue!

src/fakeplate.py

@@ -17,19 +17,24 @@ def setup_args():
     parser.add_argument('template', metavar='template.yml', type=str, nargs="?",
                         help='template to generate data from')
 
-    parser.add_argument('--csv', dest='csv', default=False, action="store_true",
-                        help='encode records as CSV')
-    parser.add_argument('--json', dest='json', default=True, action="store_true",
-                        help='encode records as JSON')
-
     parser.add_argument('--dir', dest='dir', type=str, default=".",
                         help='parent dir for templates and data files')
     parser.add_argument( '--num', dest='num_records', type=int, default=10000,
                         help='number of records to generate')
 
+    parser.add_argument('--csv', dest='csv', default=False, action="store_true",
+                        help='encode records as CSV')
+    parser.add_argument('--json', dest='json', default=True, action="store_true",
+                        help='encode records as JSON')
+
     # look up data from faker.rb
     parser.add_argument('-l', '--list', dest='list', help='list faker namespaces', action="store_true")
     parser.add_argument('-ll',  '--lookup', dest='lookup', type=str, help='faker namespace to lookup', nargs='?')
+    parser.add_argument('--debug', dest='debug', action="store_true", default=False,
+                        help='Turn on debugging output for plait.py')
+    parser.add_argument('--exit-on-error', dest='exit_error', action="store_true", default=False,
+                        help='Exit loudly on error')
+
     args = parser.parse_args()
 
     return args, parser
@@ -46,6 +51,15 @@ def main():
         fields.JSON = True
         fields.CSV = False
 
+    if args.exit_error:
+        args.debug = True
+        fields.EXIT_ON_ERROR = True
+
+    if args.debug:
+        fields.DEBUG = True
+        helpers.DEBUG = True
+
+
 
     if args.lookup:
         if args.lookup.find("#{") != -1:

src/fields.py

@@ -1051,14 +1051,18 @@ def print_record(r):
 
 
         for _ in range(num_records // chunk_size):
-            for r in self.gen_records(chunk_size):
+            for r in self.gen_records(chunk_size, print_timing=False):
                 print_record(r)
 
         if num_records % chunk_size != 0:
-            for r in self.gen_records(num_records % chunk_size):
+            for r in self.gen_records(num_records % chunk_size, print_timing=False):
                 print_record(r)
 
-    def gen_records(self, num_records):
+        self.print_dropped()
+        if DEBUG_GEN_TIMINGS:
+            self.print_timings()
+
+    def gen_records(self, num_records, print_timing=True):
         ret = []
         try:
             for i in range(num_records):
@@ -1076,8 +1080,9 @@ def gen_records(self, num_records):
         except Exception as e:
             debug(e)
         finally:
-            self.print_dropped()
-            if DEBUG_GEN_TIMINGS:
-                self.print_timings()
+            if print_timing:
+                self.print_dropped()
+                if DEBUG_GEN_TIMINGS:
+                    self.print_timings()
 
         return ret

src/version.py

@@ -1,4 +1,4 @@
-VERSION="0.0.12"
+VERSION="0.0.13"
 
 if __name__ == "__main__":
     print(VERSION)

tests/test_fields.py

@@ -223,7 +223,9 @@ def test_field_include_json(self):
 
     # test field errors
     def test_exit_on_error(self):
-        pass
+        t = fields.Template("tests/templates/bad_args.yaml")
+        with self.assertRaises(SystemExit) as context:
+            r = t.gen_record()
 
     def test_track_field_errors(self):
         pass