csvpath 0.0.2__tar.gz → 0.0.21__tar.gz

csvpath-0.0.2/README.md → csvpath-0.0.21/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.1
+Name: csvpath
+Version: 0.0.21
+Summary: 
+Author: David Kershaw
+Author-email: dk107dk@hotmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: ply (>=3.11,<4.0)
+Requires-Dist: polars (>=1.1.0,<2.0.0)
+Requires-Dist: pytest (>=8.2.2,<9.0.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Description-Content-Type: text/markdown
+
 
 # CsvPath
 
@@ -104,15 +120,26 @@ take a specific or  unlimited number of types as arguments.     </td>
     </tr>
 <table>
 
-    [ #common_name #0=="field" @tail=end() not(in(@tail, 'short|medium')) ]
+## Example
+    [ #common_name #0=="field" @tail.onmatch=end() not(in(@tail, 'short|medium')) ]
 
 In the path above, the rules applied are:
 - `#common_name` indicates a header named "common_name". Headers are the values in the 0th line. This component of the match is an existence test.
 - `#2` means the 3rd column, counting from 0
 - Functions and column references are ANDed together
-- `@tail` creates a variable named "tail" and sets it to the value of the last column
+- `@tail` creates a variable named "tail" and sets it to the value of the last column if all else matches
 - Functions can contain functions, equality tests, and/or literals
 
+Variables are always set unless they are flagged with `.onmatch`. That means:
+
+    $file.csv[*][ @imcounting.onmatch = count_lines() no()]
+
+will never set `imcounting`, but:
+
+    $file.csv[*][ @imcounting = count_lines() no()]
+
+will always set it.
+
 Most of the work of matching is done in functions. The match functions are:
 
 | Function                      | What it does                                              |Done|
@@ -122,15 +149,15 @@ Most of the work of matching is done in functions. The match functions are:
 | average(number, type)         | returns the average up to current "line", "scan", "match" | X  |
 | before(value)                 | finds things before a date, number, string                | X  |
 | concat(value, value)          | counts the number of matches                              | X  |
-| count()                       | counts the number of matches                              | X  |
-| count(value)                  | count matches of value                                    | X  |
+| [count()](csvpath/matching/functions/count.md)                       | counts the number of matches                              | X  |
+| [count(value)](csvpath/matching/functions/count.md)                  | count matches of value                                    | X  |
 | count_lines()                 | count lines to this point in the file                     | X  |
 | count_scans()                 | count lines we checked for match                          | X  |
 | divide(value, value, ...)     | divides numbers                                           | X  |
 | end()                         | returns the value of the last column                      | X  |
-| every(value, number)          | match every Nth time a value is seen                      | X  |
-| first(value)                  | match the first occurrence and capture line               | X  |
-| in(value, list)               | match in a pipe-delimited list                            | X  |
+| [every(value, number)](csvpath/matching/functions/every.md)          | match every Nth time a value is seen                      | X  |
+| [first(value, value, ...)](csvpath/matching/functions/first.md)       | match the first occurrence and capture line               | X  |
+| [in(value, list)](csvpath/matching/functions/in.md)               | match in a pipe-delimited list                            | X  |
 | increment(value, n)           | increments a variable by n each time seen                 |    |
 | isinstance(value, typestr)    | tests for "int","float","complex","bool","usd"            | X  |
 | length(value)                 | returns the length of the value                           | X  |
@@ -139,21 +166,24 @@ Most of the work of matching is done in functions. The match functions are:
 | median(value, type)           | median value up to current "line", "scan", "match"        | X  |
 | min(value, type)              | smallest value seen up to current "line", "scan", "match" | X  |
 | multiply(value, value, ...)   | multiplies numbers                                        | X  |
-| no()                          | always false                                              | X  |
+| [no()](csvpath/matching/functions/no.md)                          | always false                                              | X  |
 | not(value)                    | negates a value                                           | X  |
-| now(format)                   | a datetime, optionally formatted                          | X  |
+| [now(format)](csvpath/matching/functions/now.md)                   | a datetime, optionally formatted                          | X  |
 | or(value, value,...)          | match any one                                             | X  |
 | percent(type)                 | % of total lines for "scan", "match", "line"              | X  |
+| [print(value, str)](csvpath/matching/functions/print.md)             | when matches prints the interpolated string               | X  |
 | random(list)                  | pick from a list                                          |    |
 | random(starting, ending)      | generates a random int from starting to ending            | X  |
 | regex(regex-string)           | match on a regular expression                             | X  |
 | subtract(value, value, ...)   | subtracts numbers                                         | X  |
-| tally(value, value, ...)      | counts times values are seen, including as a set          | X  |
+| [tally(value, value, ...)](csvpath/matching/functions/tally.md)      | counts times values are seen, including as a set          | X  |
 | then(y,m,d,hh,mm,ss,format)   | a datetime, optionally formatted                          |    |
 | upper(value)                  | makes value uppercase                                     | X  |
+| yes()                         | always true                                               | X  |
 
 # Not Ready For Production
-Anything could change. This project is a hobby.
+Anything could change and performance could be better. This project is a hobby.
+
 
 
 

csvpath-0.0.2/PKG-INFO → csvpath-0.0.21/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.1
-Name: csvpath
-Version: 0.0.2
-Summary: 
-Author: David Kershaw
-Author-email: dk107dk@hotmail.com
-Requires-Python: >=3.12,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: ply (>=3.11,<4.0)
-Requires-Dist: pytest (>=8.2.2,<9.0.0)
-Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
-Description-Content-Type: text/markdown
-
 
 # CsvPath
 
@@ -118,15 +104,26 @@ take a specific or  unlimited number of types as arguments.     </td>
     </tr>
 <table>
 
-    [ #common_name #0=="field" @tail=end() not(in(@tail, 'short|medium')) ]
+## Example
+    [ #common_name #0=="field" @tail.onmatch=end() not(in(@tail, 'short|medium')) ]
 
 In the path above, the rules applied are:
 - `#common_name` indicates a header named "common_name". Headers are the values in the 0th line. This component of the match is an existence test.
 - `#2` means the 3rd column, counting from 0
 - Functions and column references are ANDed together
-- `@tail` creates a variable named "tail" and sets it to the value of the last column
+- `@tail` creates a variable named "tail" and sets it to the value of the last column if all else matches
 - Functions can contain functions, equality tests, and/or literals
 
+Variables are always set unless they are flagged with `.onmatch`. That means:
+
+    $file.csv[*][ @imcounting.onmatch = count_lines() no()]
+
+will never set `imcounting`, but:
+
+    $file.csv[*][ @imcounting = count_lines() no()]
+
+will always set it.
+
 Most of the work of matching is done in functions. The match functions are:
 
 | Function                      | What it does                                              |Done|
@@ -136,15 +133,15 @@ Most of the work of matching is done in functions. The match functions are:
 | average(number, type)         | returns the average up to current "line", "scan", "match" | X  |
 | before(value)                 | finds things before a date, number, string                | X  |
 | concat(value, value)          | counts the number of matches                              | X  |
-| count()                       | counts the number of matches                              | X  |
-| count(value)                  | count matches of value                                    | X  |
+| [count()](csvpath/matching/functions/count.md)                       | counts the number of matches                              | X  |
+| [count(value)](csvpath/matching/functions/count.md)                  | count matches of value                                    | X  |
 | count_lines()                 | count lines to this point in the file                     | X  |
 | count_scans()                 | count lines we checked for match                          | X  |
 | divide(value, value, ...)     | divides numbers                                           | X  |
 | end()                         | returns the value of the last column                      | X  |
-| every(value, number)          | match every Nth time a value is seen                      | X  |
-| first(value)                  | match the first occurrence and capture line               | X  |
-| in(value, list)               | match in a pipe-delimited list                            | X  |
+| [every(value, number)](csvpath/matching/functions/every.md)          | match every Nth time a value is seen                      | X  |
+| [first(value, value, ...)](csvpath/matching/functions/first.md)       | match the first occurrence and capture line               | X  |
+| [in(value, list)](csvpath/matching/functions/in.md)               | match in a pipe-delimited list                            | X  |
 | increment(value, n)           | increments a variable by n each time seen                 |    |
 | isinstance(value, typestr)    | tests for "int","float","complex","bool","usd"            | X  |
 | length(value)                 | returns the length of the value                           | X  |
@@ -153,22 +150,23 @@ Most of the work of matching is done in functions. The match functions are:
 | median(value, type)           | median value up to current "line", "scan", "match"        | X  |
 | min(value, type)              | smallest value seen up to current "line", "scan", "match" | X  |
 | multiply(value, value, ...)   | multiplies numbers                                        | X  |
-| no()                          | always false                                              | X  |
+| [no()](csvpath/matching/functions/no.md)                          | always false                                              | X  |
 | not(value)                    | negates a value                                           | X  |
-| now(format)                   | a datetime, optionally formatted                          | X  |
+| [now(format)](csvpath/matching/functions/now.md)                   | a datetime, optionally formatted                          | X  |
 | or(value, value,...)          | match any one                                             | X  |
 | percent(type)                 | % of total lines for "scan", "match", "line"              | X  |
+| [print(value, str)](csvpath/matching/functions/print.md)             | when matches prints the interpolated string               | X  |
 | random(list)                  | pick from a list                                          |    |
 | random(starting, ending)      | generates a random int from starting to ending            | X  |
 | regex(regex-string)           | match on a regular expression                             | X  |
 | subtract(value, value, ...)   | subtracts numbers                                         | X  |
-| tally(value, value, ...)      | counts times values are seen, including as a set          | X  |
+| [tally(value, value, ...)](csvpath/matching/functions/tally.md)      | counts times values are seen, including as a set          | X  |
 | then(y,m,d,hh,mm,ss,format)   | a datetime, optionally formatted                          |    |
 | upper(value)                  | makes value uppercase                                     | X  |
+| yes()                         | always true                                               | X  |
 
 # Not Ready For Production
-Anything could change. This project is a hobby.
-
+Anything could change and performance could be better. This project is a hobby.
 
 
 

{csvpath-0.0.2 → csvpath-0.0.21}/csvpath/csvpath.py

@@ -5,6 +5,7 @@ from csvpath.matching.matcher import Matcher
 from csvpath.matching.expression_encoder import ExpressionEncoder
 from csvpath.matching.expression_math import ExpressionMath
 from csvpath.scanning.scanner import Scanner
+import time
 
 
 class NoFileException(Exception):
@@ -13,7 +14,13 @@ class NoFileException(Exception):
 
 class CsvPath:
     def __init__(
-        self, *, filename=None, delimiter=",", quotechar='"', block_print=True
+        self,
+        *,
+        filename=None,
+        delimiter=",",
+        quotechar='"',
+        block_print=True,
+        skip_blank_lines=True,
     ):
         self.filename = filename
         self.scanner = None
@@ -30,60 +37,35 @@ class CsvPath:
         self.quotechar = quotechar
         self.block_print = block_print
         self.total_lines = -1
-        self._verbose = False
         self._dump_json = False
         self._do_math = False  # off by default, still experimental
         self._collect_matchers = False
         self.matchers = []
         self.jsons = []
+        self.matcher = None
+        self.skip_blank_lines = skip_blank_lines
 
     def dump_json(self):
         self._dump_json = not self._dump_json
 
     def parse(self, data):
+        start = time.time()
         self.scanner = Scanner()
         s, mat, mod = self._find_scan_match_modify(data)
         self.scan = s
         self.match = mat
         self.modify = mod
         self.scanner.parse(s)
-        self._load_headers()
-        self.get_total_lines()
+        end = time.time()
+        print(f"parsed: {end - start}")
+        self.get_total_lines_and_headers()
         return self.scanner
 
-    def verbose(self, set_verbose: bool = True) -> None:
-        self._verbose = set_verbose
-
-    # prints what the user needs to see
-    def verbosity(self, msg: Any) -> None:
-        if self._verbose:
-            print(f"{msg}")
-
     # prints what the developer needs to see
     def print(self, msg: str) -> None:
         if not self.block_print:
             print(msg)
 
-    def _load_headers(self) -> None:
-        with open(self.scanner.filename, "r") as file:
-            reader = csv.reader(
-                file, delimiter=self.delimiter, quotechar=self.quotechar
-            )
-            for row in reader:
-                self.headers = row
-                break
-        hs = self.headers[:]
-        self.headers = []
-        for header in hs:
-            header = header.strip()
-            header = header.replace(";", "")
-            header = header.replace(",", "")
-            header = header.replace("|", "")
-            header = header.replace("\t", "")
-            header = header.replace("`", "")
-            self.headers.append(header)
-            self.verbosity(f"header: {header}")
-
     def _find_scan_match_modify(self, data):
         scan = ""
         matches = ""
@@ -104,9 +86,6 @@ class CsvPath:
         matches = matches if len(matches) > 0 else None
         modify = modify.strip()
         modify = modify if len(modify) > 0 else None
-        self.verbosity(f"scan: {scan}")
-        self.verbosity(f"matches: {matches}")
-        self.verbosity(f"modify: {modify}")
         return scan, matches, modify
 
     def __str__(self):
@@ -158,38 +137,81 @@ class CsvPath:
     def next(self):
         if self.scanner.filename is None:
             raise NoFileException("there is no filename")
-        self.verbosity(f"filename: {self.scanner.filename}")
-        total_lines = -1
-        if self._verbose:
-            total_lines = self.get_total_lines()
-            self.verbosity(f"total lines: {total_lines}")
-
         with open(self.scanner.filename, "r") as file:
             reader = csv.reader(
                 file, delimiter=self.delimiter, quotechar=self.quotechar
             )
+            start = time.time()
             for line in reader:
-                self.verbosity(f"line number: {self.line_number} of {total_lines}")
-                if self.includes(self.line_number):
+                if self.skip_blank_lines and len(line) == 0:
+                    continue
+                if self.scanner.includes(self.line_number):
                     self.scan_count = self.scan_count + 1
-                    self.print(f"CsvPath.next: line:{line}")
-                    self.verbosity(f"scan count: {self.scan_count}")
-                    if self.matches(line):
+                    # from datetime import timedelta
+                    # startmatch = time.perf_counter()
+                    b = self.matches(line)
+                    # endmatch = time.time()
+                    # duration = timedelta(seconds=time.perf_counter()-startmatch)
+                    if b:
                         self.match_count = self.match_count + 1
-                        self.verbosity(f"match count: {self.match_count}")
                         yield line
+                    # if self.scan_count < 100:
+                    #    print(f"match {self.scan_count}: {duration}")
                 self.line_number = self.line_number + 1
+            end = time.time()
+            print(f"iterated: {end - start}")
 
     def get_total_lines(self) -> int:
         if self.total_lines == -1:
+            return self.get_total_lines_and_headers()
+        return self.total_lines
+
+    def get_total_lines_and_headers(self) -> int:
+        if self.total_lines == -1:
+            start = time.time()
             with open(self.scanner.filename, "r") as file:
                 reader = csv.reader(
                     file, delimiter=self.delimiter, quotechar=self.quotechar
                 )
+                i = 0
                 for line in reader:
+                    if i == 0:
+                        self.headers = line
+                        i += 1
                     self.total_lines += 1
+            hs = self.headers[:]
+            self.headers = []
+            for header in hs:
+                header = header.strip()
+                header = header.replace(";", "")
+                header = header.replace(",", "")
+                header = header.replace("|", "")
+                header = header.replace("\t", "")
+                header = header.replace("`", "")
+                self.headers.append(header)
+            end = time.time()
+            print(f"lines and headers: {end - start}")
         return self.total_lines
 
+    def _load_headers(self) -> None:
+        with open(self.scanner.filename, "r") as file:
+            reader = csv.reader(
+                file, delimiter=self.delimiter, quotechar=self.quotechar
+            )
+            for row in reader:
+                self.headers = row
+                break
+        hs = self.headers[:]
+        self.headers = []
+        for header in hs:
+            header = header.strip()
+            header = header.replace(";", "")
+            header = header.replace(",", "")
+            header = header.replace("|", "")
+            header = header.replace("\t", "")
+            header = header.replace("`", "")
+            self.headers.append(header)
+
     def current_line_number(self) -> int:
         return self.line_number
 
@@ -208,11 +230,14 @@ class CsvPath:
     def matches(self, line) -> bool:
         if not self.match:
             return True
-        self.print(f"CsvPath.matches: the match path: {self.match}")
-
-        matcher = Matcher(
-            csvpath=self, data=self.match, line=line, headers=self.headers
-        )
+        if self.matcher is None:
+            self.matcher = Matcher(
+                csvpath=self, data=self.match, line=line, headers=self.headers
+            )
+        else:
+            self.matcher.reset()
+            self.matcher.line = line
+        matcher = self.matcher
 
         if self._do_math:
             em = ExpressionMath()
@@ -272,42 +297,6 @@ class CsvPath:
             thevalue = self.variables[name]
         return thevalue
 
-    def includes(self, line: int) -> bool:
-        from_line = self.scanner.from_line
-        to_line = self.scanner.to_line
-        all_lines = self.scanner.all_lines
-        these = self.scanner.these
-        return self._includes(
-            line, from_line=from_line, to_line=to_line, all_lines=all_lines, these=these
-        )
-
-    def _includes(
-        self,
-        line: int,
-        *,
-        from_line: int = None,
-        to_line: int = None,
-        all_lines: bool = None,
-        these: List[int] = [],
-    ) -> bool:
-        if line is None:
-            return False
-        if from_line is None and all_lines:
-            return True
-        if from_line is not None and all_lines:
-            return line >= from_line
-        if from_line == line:
-            return True
-        if from_line is not None and to_line is not None and from_line > to_line:
-            return line >= to_line and line <= from_line
-        if from_line is not None and to_line is not None:
-            return line >= from_line and line <= to_line
-        if line in these:
-            return True
-        if to_line is not None:
-            return line < to_line
-        return False
-
     def line_numbers(self) -> Iterator[int | str]:
         these = self.scanner.these
         from_line = self.scanner.from_line

csvpath-0.0.21/csvpath/matching/functions/count.md

@@ -0,0 +1,28 @@
+
+# Count
+
+Returns the number of matches. When used alone count() gives the total matches seen up to the current line in the file.
+
+Matches can be scoped down to a contained existance test or equality. Counting an equality means a function, term, variable, or header compared to another function, term, variable, or header.
+
+When the counted match is scoped to the contained existance or equality, the count is of values seen. When counting values seen the count function stores the value-integer pairs in a dict within CsvPath's variables under a key identifying the count function. The ID of the count function is a hash by default, making it difficult for a human to understand which count the key represents. To name the count use a qualifier on the count function. A qualifier is a name that follows the function name separated by a dot, as:
+
+    count.my_named_count(#0=True)
+
+For example you can do do something like this:
+
+    $file.csv [*]
+              [
+                 @t.onmatch=count.firstname_match(#firstname=="Ants")
+                 #firstname=="Ants"
+              ]
+
+This path counts the number of matches of firstname into the path's variables so that the variable name is like:
+
+    {'firstname_match':{True:1}}
+
+
+## Examples
+
+
+

{csvpath-0.0.2 → csvpath-0.0.21}/csvpath/matching/functions/count.py

@@ -20,6 +20,9 @@ class Count(Function):
                 # contribute to if there's a match
         return self.value  # or not. we have to act as if.
 
+    def matches(self, *, skip=[]) -> bool:
+        return self.value
+
     def _get_match_count(self) -> int:
         if not self.matcher or not self.matcher.csvpath:
             print("WARNING: no csvpath. are we testing?")
@@ -31,13 +34,20 @@ class Count(Function):
         # need to apply this count function to the contained obj's value
         #
         b = self._function_or_equality.matches(skip=skip)
-        self._id = self.get_id(self._function_or_equality)
+        if not b:
+            return False
+        self._id = (
+            self.qualifier
+            if self.qualifier is not None
+            else self.get_id(self._function_or_equality)
+        )
         #
         # to_value() is often going to be a bool based on matches().
         # but in a case like: count(now('yyyy-mm-dd')) it would not be
         #
         tracked_value = self._function_or_equality.to_value(skip=skip)
         cnt = self.matcher.get_variable(self._id, tracking=tracked_value, set_if_none=0)
+        # print(f"count: cnt: {cnt}, b: {b}, tracked value: {tracked_value}")
         if b:
             cnt += 1
         self.matcher.set_variable(self._id, tracking=tracked_value, value=cnt)

csvpath-0.0.21/csvpath/matching/functions/every.md

@@ -0,0 +1,58 @@
+
+# Every
+
+Matches every N times a value is seen. Every takes two arguments: a value in the form of a function, header, or variable
+and an int that indicates how many of the value must be seen for the counter to be increased.
+
+Every creates two variables. One tracks the number of times a value is seen. The other tracks the number of times every() matched or didn't match.
+
+## Examples
+
+    $file.csv[*]
+    [
+            @t.onmatch=count()
+            every.who(#lastname, 2)
+    ]
+
+
+This path matches every other time the value of the `lastname` is seen before. It results in a variable like:
+
+    {'who_every': {'lastname': 1, 'Kermit': 1, 'Bat': 7}, 'who': {False: 6, True: 3}, 't': 3}
+
+This result indicates that the lastname column had:
+- 1 'lastname'
+- 1 'Kermit'
+- 7 'Bat'
+
+Those counts resulted in 3 matches and 6 times no match. 'lastname' and 'Kermit' didn't match because they only appear 1 time each. We would have to see 'Kermit' 2 times in order to get a match on 'Kermit'.
+
+
+    $file.csv[*]
+    [
+            @t.onmatch=count()
+            every.fish(#lastname=="Bat", 2)
+    ]
+
+For a certain .csv file, this path matches 3 times and returns variables like:
+
+    {'fish_every': {False: 2, True: 7}, 'fish': {False: 5, True: 4}, 't': 4}
+
+This means that `#lastname` was "Bat" seven times. There were 2 times `#lastname` was not "Bat". This result could be problematic because it doesn't indicate which rows it collects are the `False` rows and which were the `True` ones. If we care only about the `True` matches, we could filter out the `False` rows by selecting for `#lastname == "Bat" only.
+
+    $file.csv[*]
+    [
+            @t.onmatch=count()
+            every.fish(#lastname=="Bat", 2)
+            #lastname=="Bat"
+    ]
+
+This results in `t==3` and the list of matched rows including only the 3 matched rows. The variables look like:
+
+    {'fish_every': {False: 2, True: 7}, 'fish': {False: 5, True: 4}, 't': 3}
+
+
+
+
+
+
+

csvpath-0.0.21/csvpath/matching/functions/every.py

@@ -0,0 +1,47 @@
+from typing import Any
+from csvpath.matching.functions.function import Function, ChildrenException
+from csvpath.matching.productions.equality import Equality
+
+
+class Every(Function):
+    def to_value(self, *, skip=[]) -> Any:
+        return self.matches(skip=skip)
+
+    def matches(self, *, skip=[]) -> bool:
+        if self.value is None:
+            if len(self.children) != 1:
+                raise ChildrenException("no children. there must be 1 equality child")
+            child = self.children[0]
+            if not isinstance(child, Equality):
+                raise ChildrenException("must be 1 equality child")
+
+            ###
+            # 1. we store a count of values under the ID of left. this is the value.to_value
+            # 2. we store the every-N-seen count under the qualifier or ID of every
+            # 3. we match based on count % n == 0
+            #
+            self._id = (
+                self.qualifier if self.qualifier is not None else self.get_id(self)
+            )
+            allcount = f"{self.get_id(self)}_{'every'}"
+            tracked_value = self.children[0].left.to_value(skip=skip)
+            print(f"Every.matches: tracked_value: {tracked_value}")
+            cnt = self.matcher.get_variable(
+                allcount, tracking=tracked_value, set_if_none=0
+            )
+            cnt += 1
+            self.matcher.set_variable(allcount, tracking=tracked_value, value=cnt)
+            every = self.children[0].right.to_value()
+            print(
+                f"Every.matches: {self._id}: every: {every}, cnt: {cnt} % {every} = {cnt % every}"
+            )
+            if cnt % every == 0:
+                self.value = True
+            else:
+                self.value = False
+            everycount = self.matcher.get_variable(
+                self._id, tracking=self.value, set_if_none=0
+            )
+            everycount += 1
+            self.matcher.set_variable(self._id, tracking=self.value, value=everycount)
+        return self.value

csvpath-0.0.21/csvpath/matching/functions/first.md

@@ -0,0 +1,23 @@
+
+# First
+
+Matches the first time a value is seen. A variable tracks the first line numbers for each value. First tracks None and other values that could be hard to interpret. Internally, the magic number First.NEVER = -9999999999 indicates an unset value.
+
+## Examples
+
+    $file.csv[*][first.folks(#firstname)]
+
+This path matches when the value of the `firstname` has not been seen before. It results in a variable like:
+
+    {'folks': {'David': 1}}
+
+Multiple values can be used as arguments to first().
+
+    $file.csv[*][first.dude(#firstname, #lastname)]
+
+This path matches the first instance of the firstname and lastname column values together. The comparison simply concatenates the values. The result is a variable like:
+
+    {'dude': {'DavidKermit': 5}}
+
+
+