Add 'help function <type>' subcommand, join amount and commodity functions, as well as position and inventory functions

Author: mlell

beanquery/query_env.py

@@ -185,7 +185,7 @@ def str_(x):
     return str(x)
 
 
-@function([datetime.date], datetime.date, groups=['atomic', 'date'])
+@function([datetime.date], datetime.date, name = 'date', groups=['date'])
 @function([str], datetime.date, name='date', groups=['atomic', 'date'])
 @function([object], datetime.date, name='date', groups=['atomic', 'date'])
 def date_(x):
@@ -320,7 +320,7 @@ def weekday_(x):
     return x.strftime('%a')
 
 
-@function([], datetime.date)
+@function([], datetime.date, groups=['date'])
 def today():
     """Today's date"""
     return datetime.date.today()
@@ -387,7 +387,7 @@ def lower(string):
 NONENONE = None, None
 
 
-@function([str], datetime.date, pass_context=True, groups=['account'])
+@function([str], datetime.date, pass_context=True, groups=['account', 'metadata'])
 def open_date(context, acc):
     """Get the date of the open directive of the account."""
     open_entry, _ = context.tables['accounts'].accounts.get(acc, NONENONE)
@@ -396,7 +396,7 @@ def open_date(context, acc):
     return open_entry.date
 
 
-@function([str], datetime.date, pass_context=True, groups=['account'])
+@function([str], datetime.date, pass_context=True, groups=['account', 'metadata'])
 def close_date(context, acc):
     """Get the date of the close directive of the account."""
     _, close_entry = context.tables['accounts'].accounts.get(acc, NONENONE)
@@ -405,8 +405,8 @@ def close_date(context, acc):
     return close_entry.date
 
 
-@function([str], dict, pass_context=True, groups=['account'])
-@function([str, str], object, pass_context=True, groups=['account'])
+@function([str], dict, pass_context=True, groups=['account', 'metadata'])
+@function([str, str], object, pass_context=True, groups=['account', 'metadata'])
 def open_meta(context, account, key=None):
     """Get the metadata dict of the open directive of the account. 
     With one argument, returns all metadata as a dict object. With two
@@ -420,30 +420,30 @@ def open_meta(context, account, key=None):
 
 
 # Stub kept only for function type checking and for generating documentation.
-@function([str], object, groups=['transaction'])
+@function([str], object, groups = ['metadata'])
 def meta(context, key):
     """Get some metadata key of the posting."""
     raise NotImplementedError
 
 
 # Stub kept only for function type checking and for generating documentation.
-@function([str], object, groups=['transaction'])
+@function([str], object, groups = ['metadata'])
 def entry_meta(context, key):
     """Get some metadata key of the transaction."""
     raise NotImplementedError
 
 
 # Stub kept only for function type checking and for generating documentation.
-@function([str], object, groups=['posting'])
+@function([str], object, groups = ['metadata'])
 def any_meta(context, key):
     """Get metadata from the posting or its parent transaction if not present."""
     raise NotImplementedError
 
 
-@function([str], dict, pass_context=True)
-@function([str, str], object, pass_context=True)
-@function([str], dict, pass_context=True, name='commodity_meta')
-@function([str, str], object, pass_context=True, name='commodity_meta')
+@function([str], dict, pass_context=True, groups = ['amount', 'metadata'])
+@function([str, str], object, pass_context=True, groups = ['amount', 'metadata'])
+@function([str], dict, pass_context=True, name='commodity_meta', groups = ['amount', 'metadata'])
+@function([str, str], object, pass_context=True, name='commodity_meta', groups = ['amount', 'metadata'])
 def currency_meta(context, commodity, key=None):
     """Get the metadata dict of the commodity directive of the currency."""
     entry = context.tables['commodities'].commodities.get(commodity)
@@ -550,10 +550,10 @@ def inventory_value(context, inv, date=None):
     return inv.reduce(convert.get_value, price_map, date)
 
 
-@function([str, str], Decimal, pass_context=True)
-@function([str, str, datetime.date], Decimal, pass_context=True, name='getprice')
+@function([str, str], Decimal, pass_context=True, groups = ['position'])
+@function([str, str, datetime.date], Decimal, pass_context=True, name='getprice', groups = ['position'])
 def getprice(context, base, quote, date=None):
-    """Fetch a price."""
+    """Fetch a price. Arguments: Base currency, e.g. 'EUR'; Commodity name (string); Date: Price as of this date. Default: Latest price."""
     price_map = context.tables['prices'].price_map
     pair = (base.upper(), quote.upper())
     _, price = prices.get_price(price_map, pair, date)
@@ -872,7 +872,7 @@ def update(self, store, context):
             store[self.handle].add_amount(value)
 
 
-@aggregator([position.Position], name='sum', groups = ['position', 'inventory'])
+@aggregator([position.Position], name='sum', groups = ['position'])
 class SumPosition(query_compile.EvalAggregator):
     """Calculate the sum of the position. The result is an Inventory."""
     def __init__(self, context, operands):

beanquery/shell.py

@@ -55,12 +55,22 @@
 TYPE_CATEGORIES = {
     'amount': [amount.Amount],
     'account': [],  # Must be manually assigned as account names are strings
-    'position': [position.Position],
-    'inventory': [inventory.Inventory],
+    'position': [position.Position, inventory.Inventory],
+    'metadata': [], # Must be manually assigned, signatures in query_env.py: 'object'
     'date': [datetime.date],
     'atomic': []  # fallback, default category
 }
 
+# Category information for help display. Tuples: (title, description)
+CATEGORY_INFO = {
+    'amount': ("Amount and Commodity Functions", "An amount is a value with a currency/commodity."),
+    'account': ("Account Functions", ""),
+    'position': ("Position & Inventory Functions", "A position is a single amount held at cost.\n\nExample: 10 HOOL {100.30 USD}\n\nA collection of multiple positions is an inventory"),
+    'metadata': ("Access metadata", "Access metadata from postings, transactions, and accounts."),
+    'date': ("Date Functions", ""),
+    'atomic': ("Atomic Functions", "Work on basic types: strings, numbers, etc.")
+}
+
 
 class style:
     ERROR = '\033[31;1m'
@@ -296,7 +306,27 @@ def completenames(self, text, *ignored):
 
     def do_help(self, arg):
         """List available commands with "help" or detailed help with "help cmd"."""
-        super().do_help(arg.lower())
+        if not arg:
+            super().do_help(arg)
+            return
+            
+        # Split arg by space to get command and additional arguments
+        # e.g. "help functions amount" -> command="functions", args=["amount"]
+        parts = arg.split()
+        command = parts[0].lower()
+        args = parts[1:] if len(parts) > 1 else []
+        
+        # Check if there's a help method for this command
+        help_method = getattr(self, f'help_{command}', None)
+        if help_method and args:
+            # Call the help method with the additional arguments
+            try:
+                help_method(' '.join(args))
+            except TypeError:
+                # Fallback if the help method doesn't accept arguments
+                super().do_help(command)
+        else:
+            super().do_help(command)
 
     def do_history(self, arg):
         """Print the command-line history."""
@@ -575,9 +605,9 @@ def on_Select(self, statement):
             directive are made available in this context as well. Simple functions
             (that return a single value per row) and aggregation functions (that
             return a single value per group) are available. For the complete
-            list of supported columns and functions, see help on "targets".
-            You can also provide a wildcard here, which will select a reasonable
-            default set of columns for rendering a journal.
+            list of supported columns and functions, see help on "targets" and 
+            "functions". You can also provide a wildcard here, which will 
+            select a reasonable default set of columns for rendering a journal.
 
           from_expr: A logical expression that matches on the attributes of
             the directives (not postings). This allows you to select a subset of
@@ -654,10 +684,13 @@ def help_targets(self):
 
           {columns}
 
+          ----------------------------------------------------------------------
+
           For available functions and aggregates, see "help functions".
 
         """)
-        print(template.format(**_describe_columns(self.context.tables['postings'].columns)),
+
+        print(template.format(columns = _describe_columns(self.context.tables['postings'].columns)),
               file=self.outfile)
 
     def help_from(self):
@@ -694,51 +727,78 @@ def help_where(self):
         print(template.format(columns=_describe_columns(self.context.tables['postings'].columns)),
               file=self.outfile)
 
-    def help_functions(self):
-        """Show all available functions and aggregates grouped by type."""
-        template = textwrap.dedent("""
-
-          Functions are organized by the type of their first argument:
-
-          Amount Functions (work on amounts)
-          --------------------------------
-
-          {amount_functions}
-
-          Position Functions (work on positions)
-          ------------------------------------
-
-          {position_functions}
-
-          Inventory Functions (work on inventories)
-          ---------------------------------------
-
-          {inventory_functions}
-
-          Date Functions (work on dates)
-          ----------------------------
-
-          {date_functions}
-
-          Atomic Functions (work on basic types: strings, numbers, etc.)
-          -----------------------------------------------------------
-
-          {atomic_functions}
-
-          Aggregates
-          ----------
-
-          {aggregates}
-
-        """)
-        print(template.format(
-            amount_functions=_describe_functions(query_compile.FUNCTIONS, aggregates=False, type_filter='amount'),
-            position_functions=_describe_functions(query_compile.FUNCTIONS, aggregates=False, type_filter='position'),
-            inventory_functions=_describe_functions(query_compile.FUNCTIONS, aggregates=False, type_filter='inventory'),
-            date_functions=_describe_functions(query_compile.FUNCTIONS, aggregates=False, type_filter='date'),
-            atomic_functions=_describe_functions(query_compile.FUNCTIONS, aggregates=False, type_filter='atomic'),
-            aggregates=_describe_functions(query_compile.FUNCTIONS, aggregates=True)
-        ), file=self.outfile)
+    def help_functions(self, arg=None):
+        """Show all available functions and aggregates grouped by type.
+        
+        Usage: help functions [type]
+        
+        Without type argument, shows only category descriptions.
+        With type argument, shows functions for that specific type.
+        Available types: amount, position, date, atomic, aggregates
+        """
+        if arg is None:
+            arg = ''
+        else:
+            arg = arg.strip().lower()
+        
+        
+        if not arg:
+            # Show only category descriptions when no type specified
+            sections = []
+            sections.append("\nUsage: help functions [type]\n")
+            sections.append("Functions are organized by the type of their main argument:\n")
+            
+            for category in TYPE_CATEGORIES.keys():                    
+                title, description = CATEGORY_INFO.get(category, (f"{category.title()} Functions", ""))
+                section = f"  {category}: {title}"
+                if description:
+                    section += f" - {description}"
+                sections.append(section)
+            
+            # Add aggregates info
+            sections.append("  aggregates: Aggregation Functions - Functions that compute summary values across groups, as defined by the SELECT ... GROUP BY clause.")
+            
+            # Format output with proper wrapping and indentation
+            wrapper = textwrap.TextWrapper(width=80, subsequent_indent='    ')
+            formatted_sections = []
+            for section in sections:
+                if section.startswith('  '):
+                    # For category lines, wrap with proper indentation
+                    wrapped = wrapper.fill(section)
+                    formatted_sections.append(wrapped)
+                else:
+                    # For headers and usage, keep as is
+                    formatted_sections.append(section)
+            print('\n'.join(formatted_sections), file=self.outfile)
+            return
+        
+        # Show functions for specific type
+        if arg == 'aggregates':
+            aggregates_content = _describe_functions(query_compile.FUNCTIONS, aggregates=True)
+            if aggregates_content.strip():
+                print("Aggregates\n----------\n", file=self.outfile)
+                print(aggregates_content, file=self.outfile)
+            else:
+                print("No aggregate functions found.", file=self.outfile)
+            return
+        
+        if arg not in TYPE_CATEGORIES:
+            available_types = list(TYPE_CATEGORIES.keys()) + ['aggregates']
+            available_types = [t for t in available_types if t != 'account']  # Skip account
+            print(f"Unknown type '{arg}'. Available types: {', '.join(available_types)}", file=self.outfile)
+            return
+        
+        title, description = CATEGORY_INFO.get(arg, (f"{arg.title()} Functions", ""))
+        underline = '-' * len(title)
+        functions_content = _describe_functions(query_compile.FUNCTIONS, aggregates=False, type_filter=arg)
+        
+        if functions_content.strip():
+            print(f"{title}\n{underline}", file=self.outfile)
+            if description:
+                print(f"\n{description}", file=self.outfile)
+            print(f"\n{functions_content}", file=self.outfile)
+        else:
+            print(f"No functions found for type '{arg}'.", file=self.outfile)
 
 
 def _describe_columns(columns):