From 2611d05c39a6aa942936dd56e5ebbfc2e69a42cd Mon Sep 17 00:00:00 2001 From: Natalie Misasi <87094477+nataliemisasi@users.noreply.github.com> Date: Sat, 12 Feb 2022 23:38:24 -0600 Subject: [PATCH] Updates to Grist Functions (#125) Clarify documentation for QUOTIENT, SUMPRODUCT, UUID, REPLACE, lookupOne, lookupRecords, and $group. --- sandbox/grist/functions/math.py | 13 ++++++++++--- sandbox/grist/functions/text.py | 16 +++++++++------- sandbox/grist/records.py | 5 +++-- sandbox/grist/table.py | 24 +++++++++++++++++------- 4 files changed, 39 insertions(+), 19 deletions(-) diff --git a/sandbox/grist/functions/math.py b/sandbox/grist/functions/math.py index 97d7ac32..3ea3128a 100644 --- a/sandbox/grist/functions/math.py +++ b/sandbox/grist/functions/math.py @@ -550,7 +550,7 @@ def PRODUCT(factor1, *more_factors): def QUOTIENT(dividend, divisor): """ - Returns one number divided by another. + Returns one number divided by another, without the remainder. >>> QUOTIENT(5, 2) 2 @@ -797,7 +797,8 @@ def SUMIFS(sum_range, criteria_range1, criterion1, *args): def SUMPRODUCT(array1, *more_arrays): """ - Multiplies corresponding components in the given arrays, and returns the sum of those products. + Multiplies corresponding components in two equally-sized arrays, + and returns the sum of those products. >>> SUMPRODUCT([3,8,1,4,6,9], [2,6,5,7,7,3]) 156 @@ -859,7 +860,13 @@ def TRUNC(value, places=0): return ROUNDDOWN(value, places) def UUID(): - """Generate a random UUID-formatted string identifier.""" + """ + Generate a random UUID-formatted string identifier. + Since UUID() produces a different value each time it's called, it is best to use it in + [trigger formula](https://support.getgrist.com/formulas/#trigger-formulas) for new records. + This would only calculate UUID() once and freeze the calculated value. By contrast, a regular [formula] + may get recalculated any time the document is reloaded, producing a different value for UUID() each time. + """ if six.PY2: return str(uuid.UUID(bytes=[chr(random.randrange(0, 256)) for _ in xrange(0, 16)], version=4)) else: diff --git a/sandbox/grist/functions/text.py b/sandbox/grist/functions/text.py index ee9a3b15..68c1bb69 100644 --- a/sandbox/grist/functions/text.py +++ b/sandbox/grist/functions/text.py @@ -220,7 +220,9 @@ def LEFT(string, num_chars=1): def LEN(text): """ - Returns the number of characters in a text string. Same as `len(text)`. + Returns the number of characters in a text string, or the number of items in a list. Same as + [`len`](https://docs.python.org/3/library/functions.html#len) in python. + See [Record Set](https://support.getgrist.com/functions/#recordset) for an example of using `len` on a list of records. >>> LEN("Phoenix, AZ") 11 @@ -339,9 +341,9 @@ def REGEXREPLACE(text, regular_expression, replacement): return re.sub(regular_expression, replacement, text) -def REPLACE(old_text, start_num, num_chars, new_text): +def REPLACE(text, position, length, new_text): """ - Replaces part of a text string with a different text string. Start_num is counted from 1. + Replaces part of a text string with a different text string. Position is counted from 1. >>> REPLACE("abcdefghijk", 6, 5, "*") 'abcde*k' @@ -354,11 +356,11 @@ def REPLACE(old_text, start_num, num_chars, new_text): >>> REPLACE('foo', 0, 1, 'bar') Traceback (most recent call last): ... - ValueError: start_num invalid + ValueError: position invalid """ - if start_num < 1: - raise ValueError("start_num invalid") - return old_text[:start_num - 1] + new_text + old_text[start_num - 1 + num_chars:] + if position < 1: + raise ValueError("position invalid") + return text[:position - 1] + new_text + text[position - 1 + length:] def REPT(text, number_times): diff --git a/sandbox/grist/records.py b/sandbox/grist/records.py index 5b244188..2d68cbfd 100644 --- a/sandbox/grist/records.py +++ b/sandbox/grist/records.py @@ -38,8 +38,9 @@ class Record(object): Name: $group, rec.group Usage: __$group__ - In a summary view, `$group` is a special field containing the list of Records that are - summarized by the current summary line. E.g. `len($group)` is the count of those records. + In a [summary table](https://support.getgrist.com/summary-tables/), `$group` is a special field + containing the list of Records that are summarized by the current summary line. E.g. the formula + `len($group)` counts the number of those records being summarized in each row. See [RecordSet](#recordset) for useful properties offered by the returned object. diff --git a/sandbox/grist/table.py b/sandbox/grist/table.py index 47e4ae04..ef0f7209 100644 --- a/sandbox/grist/table.py +++ b/sandbox/grist/table.py @@ -79,13 +79,18 @@ class UserTable(object): # and we decided camelCase was a more user-friendly choice for user-facing functions. def lookupRecords(self, **field_value_pairs): """ - Returns the Records from this table that match the given field=value arguments. If - `sort_by=field` is given, sort the results by that field. + Name: lookupRecords + Usage: UserTable.__lookupRecords__(Field_In_Lookup_Table=value, ...) + Returns a RecordSet matching the given field=value arguments. The value may be any expression, + most commonly a field in the current row (e.g. `$SomeField`) or a constant (e.g. a quoted string + like `"Some Value"`) (examples below). + If `sort_by=field` is given, sort the results by that field. For example: ``` - People.lookupRecords(Last_Name="Johnson", sort_by="First_Name") - People.lookupRecords(First_Name="George", Last_Name="Washington") + People.*lookupRecords*(Email=$Work_Email) + People.*lookupRecords*(First_Name="George", Last_Name="Washington") + People.*lookupRecords*(Last_Name="Johnson", sort_by="First_Name") ``` See [RecordSet](#recordset) for useful properties offered by the returned object. @@ -98,12 +103,17 @@ class UserTable(object): def lookupOne(self, **field_value_pairs): """ - Returns a Record matching the given field=value arguments. If multiple records match, returns - one of them. If none match, returns the special empty record. + Name: lookupOne + Usage: UserTable.__lookupOne__(Field_In_Lookup_Table=value, ...) + Returns a Record matching the given field=value arguments. The value may be any expression, + most commonly a field in the current row (e.g. `$SomeField`) or a constant (e.g. a quoted string + like `"Some Value"`). If multiple records match, returns one of them. If none match, returns the + special empty record. For example: ``` - People.lookupOne(First_Name="Lewis", Last_Name="Carroll") + People.*lookupOne*(First_Name="Lewis", Last_Name="Carroll") + People.*lookupOne*(Email=$Work_Email) ``` """ return self.table.lookup_one_record(**field_value_pairs)