Functional updates to add line function support. Bumped version and updated docs.

Author: jeffrimko

CHANGELOG.adoc

@@ -1,5 +1,15 @@
 = Verace Changelog
 
+== verace-0.4.0 (2018-01-15)
+=== Release highlights
+  - Non-breaking functional updates.
+
+=== All additions and changes
+  - Added support for line functions.
+
+=== Bug fixes
+  - Minor fix for functions that return no `VerInfo`.
+
 == verace-0.3.2 (2018-01-14)
 === Release highlights
   - Minor tweaks.

README.adoc

@@ -49,7 +49,7 @@ Get the string found by the checker:
 [source,python]
 --------
 print("version found = " + mychk.string())
-# version found = 0.3.2
+# version found = 0.4.0
 --------
 
 The string can be updated in all associated files:

doc/source/conf.py

@@ -53,9 +53,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.3.2'
+version = u'0.4.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.3.2'
+release = u'0.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/index.rst

@@ -18,14 +18,24 @@ This class is used to create objects that will check/update strings in files:
 
 Custom Check Functions
 ----------------------
-A function can be provided to ``VerChecker.include()``. If no explicit function is provide, the following function will be used:
+A function can be provided to ``VerChecker.include()``. The function will be used to parse the file for the target string.
+
+If a tuple/list is provided as as the ``func`` argument, the first value must be a function and the second value must be the string ``'file'`` (default) or ``'line'``.
+
+If no explicit function is provide, the following file function will be used:
 
 .. autofunction:: verace.check_basic
 
-Custom functions can be defined to find strings. The first argument must be the file path and the function must return either a single ``VerInfo`` object or a list of ``VerInfo`` objects:
+File Functions
+~~~~~~~~~~~~~~
+File functions must handle the string search through the entire target file. The first argument must be the file path and the function must return either a single ``VerInfo`` object or a list of ``VerInfo`` objects:
 
 .. autodata:: verace.VerInfo
 
 Use this convenience function to iterate through the lines in a given file:
 
 .. autofunction:: verace.readlines
+
+Line Functions
+~~~~~~~~~~~~~~
+Line functions will be provided each line from the file one at a time. If the target string is found, simply return it. Otherwise return None (default return).

lib/setup.py

@@ -3,7 +3,7 @@
 
 setup(
     name = "verace",
-    version = "0.3.2",
+    version = "0.4.0",
     author = "Jeff Rimko",
     author_email = "jeffrimko@gmail.com",
     description = "Library for checking version strings in project files.",

lib/verace.py

@@ -21,7 +21,7 @@
 ##==============================================================#
 
 #: Library version string.
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 
 #: Contains information for a single checked item.
 VerInfo = namedtuple("VerInfo", "path linenum string")
@@ -48,6 +48,42 @@ def __init__(self, name, root):
         self._string = None
         self._checks = []
         self.debug = False
+    def _run_check(self, c):
+        """Runs a single VerCheck and returns a list of (VerInfo,updatable)
+        tuples."""
+        dprint = get_vprint(self.debug)
+        # Setup file path.
+        path = c.path
+        if not op.isabs(path):
+            path = op.join(self.root, path)
+        path = op.normpath(path)
+        # Setup function and function type.
+        if type(c.func) in [list, tuple]: func,ftyp = c.func
+        else: func,ftyp = (c.func, "file")
+        if (not func) or (not hasattr(func, "__call__")):
+            func = check_basic
+        # Run the function over the file and collect VerInfo objects.
+        vinfos = []
+        if "file" == ftyp:
+            v = func(path, **c.opts)
+            dprint((inspect.stack()[0][3], c, v))
+            if list != type(v): v = [v]
+            vinfos += v
+        elif "line" == ftyp:
+            for num,line in readlines(path):
+                string = func(line, **c.opts)
+                if string:
+                    vinfos.append(VerInfo(path, num, string))
+        return [(v, c.updatable) for v in vinfos if v]
+    def _iter_vinfo(self, get_updatable=False):
+        """Iterates over the associated VerInfo objects. Optionally returns if
+        the associated file is updatable."""
+        vlist = [] # Holds (VerInfo,updatable) items.
+        for c in self._checks:
+            vlist += self._run_check(c)
+        for vu in sorted(vlist, key=lambda i: (i[0].path, i[0].linenum)):
+            if vu:
+                yield vu if get_updatable else vu[0]
     def string(self):
         """Returns the string if `run()` found no inconsistencies,
         otherwise None is returned. Always calls `run()`."""
@@ -58,45 +94,28 @@ def include(self, path, func=None, opts=None, updatable=True, **kwargs):
 
         **Params**:
           - path (str) - Path to a file to check.
-          - func (function) - Function that performs check will be passed
-            `path` and `opts`. Must return a VerInfo (single or list).
+          - func (function|(tuple,str)) - Either a (func,type) tuple or a
+            function (type defaults to 'file'). Valid type values are
+            'file|line'. The type controls whether the file path or individual
+            lines will be passed to the function. A file function may return
+            either single VerInfo or a list of VerInfos. A line function may
+            return a string.
           - opts (dict) - Options to pass to the check function. Any additional
             keyword args will be included.
           - updatable (bool) - If true, string can be updated using `update()`.
         """
         if not opts:
             opts = {}
         opts.update(copy.deepcopy(kwargs))
-        if (not func) or (not hasattr(func, "__call__")):
-            func = check_basic
         c = VerCheck(path, func, copy.deepcopy(opts), updatable)
         self._checks.append(c)
-    def iter_vinfo(self, get_updatable=False):
-        """Iterates over the associated VerInfo objects. Optionally returns if
-        the associated file is updatable."""
-        dprint = get_vprint(self.debug)
-        vlist = [] # Holds (vinfo,updatable) items.
-        for c in self._checks:
-            path = c.path
-            if not op.isabs(path):
-                path = op.join(self.root, path)
-            path = op.normpath(path)
-            vinfos = c.func(path, **c.opts)
-            dprint((inspect.stack()[0][3], c, vinfos))
-            if list != type(vinfos):
-                vinfos = [vinfos]
-            for v in vinfos:
-                vlist.append((v,c.updatable))
-        for vu in sorted(vlist, key=lambda i: (i[0].path, i[0].linenum)):
-            if vu:
-                yield vu if get_updatable else vu[0]
     def run(self, verbose=True):
         """Runs checks on all included items, reports any inconsistencies.
         Returns string if consistent else None."""
         vprint = get_vprint(verbose)
         strings = []
         vprint(self.name + ":")
-        for vinfo in self.iter_vinfo():
+        for vinfo in self._iter_vinfo():
             if vinfo.string not in strings:
                 strings.append(vinfo.string)
             vprint("  `%s` (%s:%u)" % (
@@ -116,7 +135,7 @@ def update(self, newstr):
         caution as this will modify file content! Returns number of strings
         updated."""
         updated = 0
-        for vinfo,updatable in self.iter_vinfo(get_updatable=True):
+        for vinfo,updatable in self._iter_vinfo(get_updatable=True):
             if not updatable:
                 continue
             with open(vinfo.path) as fi:

tests/linefunc_test_1.py

@@ -0,0 +1,45 @@
+"""Tests the basic usage of VerChecker."""
+
+##==============================================================#
+## SECTION: Imports                                             #
+##==============================================================#
+
+from testlib import *
+
+from verace import VerChecker
+
+##==============================================================#
+## SECTION: Class Definitions                                   #
+##==============================================================#
+
+class TestCase(unittest.TestCase):
+
+    def setUp(test):
+        test.verchk = VerChecker("Basic Version", __file__)
+
+    def test_version(test):
+        def getver(line):
+            if "version =" in line:
+                return line.split('"')[1]
+        test.verchk.include("checkfiles/multi.txt", func=(getver, "line"))
+        test.assertEqual(test.verchk.string(), "1.2.3")
+
+    def test_different(test):
+        def getdiff(line):
+            if "different =" in line:
+                return line.split('"')[1].split(",")[0]
+        test.verchk.include("checkfiles/multi.txt", func=(getdiff, "line"))
+        test.assertEqual(test.verchk.string(), "0.0.0")
+
+    def test_none(test):
+        def getnone(line):
+            return
+        test.verchk.include("checkfiles/multi.txt", func=(getnone, "line"))
+        test.assertEqual(test.verchk.string(), None)
+
+##==============================================================#
+## SECTION: Main Body                                           #
+##==============================================================#
+
+if __name__ == '__main__':
+    unittest.main()