From 40c87f45296a04c4c5092dc6f4c797c27260979e Mon Sep 17 00:00:00 2001 From: Dmitry S Date: Wed, 12 Jun 2024 17:47:25 -0400 Subject: [PATCH] (core) Update documentation of certain functions Summary: - lookupOne/lookupRecords explain `sort_by` param better, and link to more detailed article. - Incorporate a typo fix from Help Center - Fix the omission of TASTEME never having been documented. Test Plan: Corresponding update to Help Center can be reviewed at https://github.com/gristlabs/grist-help/pull/351 Reviewers: jarek Reviewed By: jarek Subscribers: jarek Differential Revision: https://phab.getgrist.com/D4269 --- sandbox/grist/functions/text.py | 18 +++++++++++++++--- sandbox/grist/table.py | 19 ++++++++++++++++--- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/sandbox/grist/functions/text.py b/sandbox/grist/functions/text.py index 3d9a7c0d..0fe8c4ca 100644 --- a/sandbox/grist/functions/text.py +++ b/sandbox/grist/functions/text.py @@ -647,6 +647,18 @@ def T(value): six.text_type(value) if isinstance(value, AltText) else u"") def TASTEME(food): + """ + For any given piece of text, decides if it is tasty or not. + + This is not serious. It appeared as an Easter egg, and is kept as such. It is in fact a puzzle + to figure out the underlying simple rule. It has been surprisingly rarely cracked, even after + reading the source code, which is freely available and may entertain Python fans. + + >>> TASTEME('Banana') + True + >>> TASTEME('Garlic') + False + """ chews = re.findall(r'\b[A-Z]+\b', food.upper()) claw = slice(2, None) spit = lambda chow: chow[claw] @@ -657,9 +669,9 @@ def TASTEME(food): @unimplemented def TEXT(number, format_type): # pylint: disable=unused-argument """ - Converts a number into text according to a specified format. It is not yet implemented in + Converts a number into text according to a specified format. It is not yet implemented in Grist. You can use the similar Python functions str() to convert numbers into strings, and - optionally format() to specify the number format. + optionally format() to specify the number format. """ raise NotImplementedError() @@ -681,7 +693,7 @@ def TRIM(text): def UPPER(text): """ - Converts a specified string to uppercase. Same as `text.lower()`. + Converts a specified string to uppercase. Same as `text.upper()`. >>> UPPER("e. e. cummings") 'E. E. CUMMINGS' diff --git a/sandbox/grist/table.py b/sandbox/grist/table.py index 9b976403..b582ab9d 100644 --- a/sandbox/grist/table.py +++ b/sandbox/grist/table.py @@ -68,13 +68,17 @@ class UserTable(object): 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. + + You may set the optional `sort_by` parameter to the column ID by which to sort multiple matching + results, to determine which of them is returned. You can prefix the column ID with "-" to + reverse the order. For example: ``` People.lookupRecords(Email=$Work_Email) People.lookupRecords(First_Name="George", Last_Name="Washington") People.lookupRecords(Last_Name="Johnson", sort_by="First_Name") + Orders.lookupRecords(Customer=$id, sort_by="-OrderDate") ``` See [RecordSet](#recordset) for useful properties offered by the returned object. @@ -82,6 +86,8 @@ class UserTable(object): See [CONTAINS](#contains) for an example utilizing `UserTable.lookupRecords` to find records where a field of a list type (such as `Choice List` or `Reference List`) contains the given value. + + Learn more about [lookupRecords](references-lookups.md#lookuprecords). """ return self.table.lookup_records(**field_value_pairs) @@ -92,14 +98,21 @@ class UserTable(object): Returns a [Record](#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. + like `"Some Value"`). If multiple records are found, the first match is returned. + + You may set the optional `sort_by` parameter to the column ID by which to sort multiple matching + results, to determine which of them is returned. You can prefix the column ID with "-" to + reverse the order. For example: ``` People.lookupOne(First_Name="Lewis", Last_Name="Carroll") People.lookupOne(Email=$Work_Email) + Tickets.lookupOne(Person=$id, sort_by="Date") # Find the first ticket for the person + Tickets.lookupOne(Person=$id, sort_by="-Date") # Find the last ticket for the person ``` + + Learn more about [lookupOne](references-lookups.md#lookupone). """ return self.table.lookup_one_record(**field_value_pairs)