singlestoredb 1.0.4__py3-none-any.whl → 1.2.0__py3-none-any.whl

singlestoredb/fusion/handler.py

@@ -45,6 +45,8 @@ BUILTINS = {
     '<limit>': r'''
     limit = LIMIT <integer>
     ''',
+    '<integer>': '',
+    '<number>': '',
 }
 
 BUILTIN_DEFAULTS = {  # type: ignore
@@ -170,8 +172,8 @@ def build_cmd(grammar: str) -> str:
     return f'{space}{cmd} ={begin}\n{end}'
 
 
-def build_help(grammar: str) -> str:
-    """Construct full help syntax."""
+def build_syntax(grammar: str) -> str:
+    """Construct full syntax."""
     if ';' not in grammar:
         raise ValueError('a semi-colon exist at the end of the primary rule')
 
@@ -199,8 +201,102 @@ def build_help(grammar: str) -> str:
     return cmd
 
 
+def _format_examples(ex: str) -> str:
+    """Convert examples into sections."""
+    return re.sub(r'(^Example\s+\d+.*$)', r'### \1', ex, flags=re.M)
+
+
+def _format_arguments(arg: str) -> str:
+    """Format arguments as subsections."""
+    out = []
+    for line in arg.split('\n'):
+        if line.startswith('<'):
+            out.append(f'### {line.replace("<", "&lt;").replace(">", "&gt;")}')
+            out.append('')
+        else:
+            out.append(line.strip())
+    return '\n'.join(out)
+
+
+def _to_markdown(txt: str) -> str:
+    """Convert formatting to markdown."""
+    txt = re.sub(r'`([^`]+)\s+\<([^\>]+)>`_', r'[\1](\2)', txt)
+    txt = txt.replace('``', '`')
+
+    # Format code blocks
+    lines = re.split(r'\n', txt)
+    out = []
+    while lines:
+        line = lines.pop(0)
+        if line.endswith('::'):
+            out.append(line[:-2] + '.')
+            code = []
+            while lines and (not lines[0].strip() or lines[0].startswith(' ')):
+                code.append(lines.pop(0).rstrip())
+            code_str = re.sub(r'^\s*\n', r'', '\n'.join(code).rstrip())
+            out.extend([f'```sql\n{code_str}\n```\n'])
+        else:
+            out.append(line)
+
+    return '\n'.join(out)
+
+
+def build_help(syntax: str, grammar: str) -> str:
+    """Build full help text."""
+    cmd = re.match(r'([A-Z0-9_ ]+)', syntax.strip())
+    if not cmd:
+        raise ValueError(f'no command found: {syntax}')
+
+    out = [f'# {cmd.group(1)}\n\n']
+
+    sections: Dict[str, str] = {}
+    grammar = textwrap.dedent(grammar.rstrip())
+    desc_re = re.compile(r'^([A-Z][\S ]+)\s*^\-\-\-\-+\s*$', flags=re.M)
+    if desc_re.search(grammar):
+        _, *txt = desc_re.split(grammar)
+        txt = [x.strip() for x in txt]
+        sections = {}
+        while txt:
+            key = txt.pop(0)
+            value = txt.pop(0)
+            sections[key.lower()] = _to_markdown(value).strip()
+
+    if 'description' in sections:
+        out.extend([sections['description'], '\n\n'])
+
+    out.append(f'## Syntax\n\n```sql{syntax}\n```\n\n')
+
+    if 'arguments' in sections:
+        out.extend([
+            '## Arguments\n\n',
+            _format_arguments(sections['arguments']),
+            '\n\n',
+        ])
+    if 'argument' in sections:
+        out.extend([
+            '## Argument\n\n',
+            _format_arguments(sections['argument']),
+            '\n\n',
+        ])
+
+    if 'remarks' in sections:
+        out.extend(['## Remarks\n\n', sections['remarks'], '\n\n'])
+
+    if 'examples' in sections:
+        out.extend(['## Examples\n\n', _format_examples(sections['examples']), '\n\n'])
+    elif 'example' in sections:
+        out.extend(['## Example\n\n', _format_examples(sections['example']), '\n\n'])
+
+    if 'see also' in sections:
+        out.extend(['## See Also\n\n', sections['see also'], '\n\n'])
+
+    return ''.join(out).rstrip() + '\n'
+
+
 def strip_comments(grammar: str) -> str:
     """Strip comments from grammar."""
+    desc_re = re.compile(r'(^\s*Description\s*^\s*-----------\s*$)', flags=re.M)
+    grammar = desc_re.split(grammar, maxsplit=1)[0]
     return re.sub(r'^\s*#.*$', r'', grammar, flags=re.M)
 
 
@@ -226,7 +322,9 @@ def inject_builtins(grammar: str) -> str:
     return grammar
 
 
-def process_grammar(grammar: str) -> Tuple[Grammar, Tuple[str, ...], Dict[str, Any], str]:
+def process_grammar(
+    grammar: str,
+) -> Tuple[Grammar, Tuple[str, ...], Dict[str, Any], str, str]:
     """
     Convert SQL grammar to a Parsimonious grammar.
 
@@ -247,10 +345,12 @@ def process_grammar(grammar: str) -> Tuple[Grammar, Tuple[str, ...], Dict[str, A
     rules = {}
     rule_info = {}
 
+    full_grammar = grammar
     grammar = strip_comments(grammar)
     grammar = inject_builtins(grammar)
     command_key = get_keywords(grammar)
-    help_txt = build_help(grammar)
+    syntax_txt = build_syntax(grammar)
+    help_txt = build_help(syntax_txt, full_grammar)
     grammar = build_cmd(grammar)
 
     # Make sure grouping characters all have whitespace around them
@@ -336,7 +436,10 @@ def process_grammar(grammar: str) -> Tuple[Grammar, Tuple[str, ...], Dict[str, A
     cmds = ' / '.join(x for x in rules if x.endswith('_cmd'))
     cmds = f'init = ws* ( {cmds} ) ws* ";"? ws*\n'
 
-    return Grammar(cmds + CORE_GRAMMAR + '\n'.join(out)), command_key, rule_info, help_txt
+    return (
+        Grammar(cmds + CORE_GRAMMAR + '\n'.join(out)), command_key,
+        rule_info, syntax_txt, help_txt,
+    )
 
 
 def flatten(items: Iterable[Any]) -> List[Any]:
@@ -378,7 +481,10 @@ class SQLHandler(NodeVisitor):
     #: Metadata about the parse rules
     rule_info: Dict[str, Any] = {}
 
-    #: Help string for use in error messages
+    #: Syntax string for use in error messages
+    syntax: str = ''
+
+    #: Full help for the command
     help: str = ''
 
     #: Rule validation functions
@@ -396,7 +502,7 @@ class SQLHandler(NodeVisitor):
         Compile the grammar held in the docstring.
 
         This method modifies attributes on the class: ``grammar``,
-        ``command_key``, ``rule_info``, and ``help``.
+        ``command_key``, ``rule_info``, ``syntax``, and ``help``.
 
         Parameters
         ----------
@@ -407,7 +513,7 @@ class SQLHandler(NodeVisitor):
         if cls._is_compiled:
             return
 
-        cls.grammar, cls.command_key, cls.rule_info, cls.help = \
+        cls.grammar, cls.command_key, cls.rule_info, cls.syntax, cls.help = \
             process_grammar(grammar or cls.__doc__ or '')
 
         cls._grammar = grammar or cls.__doc__ or ''
@@ -476,7 +582,7 @@ class SQLHandler(NodeVisitor):
                 msg = ' ' + m.group(1) + m.group(2)
             raise ValueError(
                 f'Could not parse statement.{msg} '
-                'Expecting:\n' + textwrap.indent(type(self).help, '  '),
+                'Expecting:\n' + textwrap.indent(type(self).syntax, '  '),
             )
 
     @abc.abstractmethod

singlestoredb/fusion/handlers/stage.py

@@ -12,8 +12,10 @@ from .utils import get_workspace_group
 
 class ShowStageFilesHandler(SQLHandler):
     """
-    SHOW STAGE FILES [ in_group ] [ at_path ] [ <like> ] [ <order-by> ]
-                     [ <limit> ] [ recursive ] [ extended ];
+    SHOW STAGE FILES [ in_group ]
+        [ at_path ] [ <like> ]
+        [ <order-by> ]
+        [ <limit> ] [ recursive ] [ extended ];
 
     # Workspace group
     in_group = IN GROUP { group_id | group_name }
@@ -33,7 +35,56 @@ class ShowStageFilesHandler(SQLHandler):
     # Should extended attributes be shown?
     extended = EXTENDED
 
-    """
+    Description
+    -----------
+    Displays a list of files in a Stage.
+
+    Refer to `Stage <https://docs.singlestore.com/cloud/developer-resources/stage-storage-service/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<group_id>``: The ID of the workspace group in which
+      the Stage is attached.
+    * ``<group_name>``: The name of the workspace group in which
+      the Stage is attached.
+    * ``<path>``: A path in the Stage.
+    * ``<pattern>``: A pattern similar to SQL LIKE clause.
+      Uses ``%`` as the wildcard character.
+
+    Remarks
+    -------
+    * Use the ``LIKE`` clause to specify a pattern and return only the
+      files that match the specified pattern.
+    * The ``LIMIT`` clause limits the number of results to the
+      specified number.
+    * Use the ``ORDER BY`` clause to sort the results by the specified
+      key. By default, the results are sorted in the ascending order.
+    * The ``AT PATH`` clause specifies the path in the Stage to list
+      the files from.
+    * The ``IN GROUP`` clause specifies the ID or the name of the
+      workspace group in which the Stage is attached.
+    * Use the ``RECURSIVE`` clause to list the files recursively.
+    * To return more information about the files, use the ``EXTENDED``
+      clause.
+
+    Examples
+    --------
+    The following command lists the files at a specific path::
+
+        SHOW STAGE FILES IN GROUP 'wsg1' AT PATH "/data/";
+
+    The following command lists the files recursively with
+    additional information::
+
+        SHOW STAGE FILES IN GROUP 'wsg1' RECURSIVE EXTENDED;
+
+    See Also
+    --------
+    * ``UPLOAD FILE TO STAGE``
+    * ``DOWNLOAD STAGE FILE``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         wg = get_workspace_group(params)
@@ -80,7 +131,9 @@ ShowStageFilesHandler.register(overwrite=True)
 
 class UploadStageFileHandler(SQLHandler):
     """
-    UPLOAD FILE TO STAGE stage_path [ in_group ] FROM local_path [ overwrite ];
+    UPLOAD FILE TO STAGE stage_path
+        [ in_group ]
+        FROM local_path [ overwrite ];
 
     # Path to stage file
     stage_path = '<stage-path>'
@@ -100,7 +153,43 @@ class UploadStageFileHandler(SQLHandler):
     # Should an existing file be overwritten?
     overwrite = OVERWRITE
 
-    """
+    Description
+    -----------
+    Uploads a file to a Stage.
+
+    Refer to `Stage <https://docs.singlestore.com/cloud/developer-resources/stage-storage-service/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<stage_path>``: The path in the Stage where the file is uploaded.
+    * ``<group_id>``: The ID of the workspace group in which the Stage
+      is attached.
+    * ``<group_name>``: The name of the workspace group in which the
+      Stage is attached.
+    * ``<local-path>``: The path to the file to upload in the local
+      directory.
+
+    Remarks
+    -------
+    * The ``IN GROUP`` clause specifies the ID or the name of the workspace
+      group in which the Stage is attached.
+    * If the ``OVERWRITE`` clause is specified, any existing file at the
+      specified path in the Stage is overwritten.
+
+    Examples
+    --------
+    The following command uploads a file to a Stage and overwrites any
+    existing files at the specified path::
+
+        UPLOAD FILE TO STAGE '/data/stats.csv' IN GROUP 'wsg1'
+            FROM '/tmp/user/stats.csv' OVERWRITE;
+
+    See Also
+    --------
+    * ``DOWNLOAD STAGE FILE``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         wg = get_workspace_group(params)
@@ -116,8 +205,11 @@ UploadStageFileHandler.register(overwrite=True)
 
 class DownloadStageFileHandler(SQLHandler):
     """
-    DOWNLOAD STAGE FILE stage_path [ in_group ] [ local_path ]
-                                   [ overwrite ] [ encoding ];
+    DOWNLOAD STAGE FILE stage_path
+        [ in_group ]
+        [ local_path ]
+        [ overwrite ]
+        [ encoding ];
 
     # Path to stage file
     stage_path = '<stage-path>'
@@ -140,7 +232,54 @@ class DownloadStageFileHandler(SQLHandler):
     # File encoding
     encoding = ENCODING '<encoding>'
 
-    """
+    Description
+    -----------
+    Download a file from a Stage.
+
+    Refer to `Stage <https://docs.singlestore.com/cloud/developer-resources/stage-storage-service/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<stage_path>``: The path to the file to download in a Stage.
+    * ``<group_id>``: The ID of the workspace group in which the
+      Stage is attached.
+    * ``<group_name>``: The name of the workspace group in which the
+      Stage is attached.
+    * ``<encoding>``: The encoding to apply to the downloaded file.
+    * ``<local-path>``: Specifies the path in the local directory
+      where the file is downloaded.
+
+    Remarks
+    -------
+    * If the ``OVERWRITE`` clause is specified, any existing file at
+      the download location is overwritten.
+    * The ``IN GROUP`` clause specifies the ID or the name of the
+      workspace group in which the Stage is attached.
+    * By default, files are downloaded in binary encoding. To view
+      the contents of the file on the standard output, use the
+      ``ENCODING`` clause and specify an encoding.
+    * If ``<local-path>`` is not specified, the file is displayed
+      on the standard output.
+
+    Examples
+    --------
+    The following command displays the contents of the file on the
+    standard output::
+
+        DOWNLOAD STAGE FILE '/data/stats.csv' IN GROUP 'wsgroup1' ENCODING 'utf8';
+
+    The following command downloads a file to a specific location and
+    overwrites any existing file with the name ``stats.csv`` on the local storage::
+
+        DOWNLOAD STAGE FILE '/data/stats.csv' IN GROUP 'wsgroup1'
+            TO '/tmp/data.csv' OVERWRITE;
+
+    See Also
+    --------
+    * ``UPLOAD FILE TO STAGE``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         wg = get_workspace_group(params)
@@ -169,7 +308,8 @@ DownloadStageFileHandler.register(overwrite=True)
 
 class DropStageFileHandler(SQLHandler):
     """
-    DROP STAGE FILE stage_path [ in_group ];
+    DROP STAGE FILE stage_path
+        [ in_group ];
 
     # Path to stage file
     stage_path = '<stage-path>'
@@ -183,7 +323,38 @@ class DropStageFileHandler(SQLHandler):
     # Name of group
     group_name = '<group-name>'
 
-    """
+    Description
+    -----------
+    Deletes a file from a Stage.
+
+    Refer to `Stage <https://docs.singlestore.com/cloud/developer-resources/stage-storage-service/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<stage_path>``: The path to the file to delete in a Stage.
+    * ``<group_id>``: The ID of the workspace group in which the
+      Stage is attached.
+    * ``<group_name>``: The name of the workspace group in which
+      the Stage is attached.
+
+    Remarks
+    -------
+    * The ``IN GROUP`` clause specifies the ID or the name of the
+      workspace group in which the Stage is attached.
+
+    Example
+    --------
+    The following command deletes a file from a Stage attached to
+    a workspace group named **wsg1**::
+
+        DROP STAGE FILE '/data/stats.csv' IN GROUP 'wsg1';
+
+    See Also
+    --------
+    * ``DROP STAGE FOLDER``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         wg = get_workspace_group(params)
@@ -196,7 +367,9 @@ DropStageFileHandler.register(overwrite=True)
 
 class DropStageFolderHandler(SQLHandler):
     """
-    DROP STAGE FOLDER stage_path [ in_group ] [ recursive ];
+    DROP STAGE FOLDER stage_path
+        [ in_group ]
+        [ recursive ];
 
     # Path to stage folder
     stage_path = '<stage-path>'
@@ -213,7 +386,38 @@ class DropStageFolderHandler(SQLHandler):
     # Should folers be deleted recursively?
     recursive = RECURSIVE
 
-    """
+    Description
+    -----------
+    Deletes a folder from a Stage.
+
+    Refer to `Stage <https://docs.singlestore.com/cloud/developer-resources/stage-storage-service/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<stage_path>``: The path to the folder to delete in a Stage.
+    * ``<group_id>``: The ID of the workspace group in which the
+      Stage is attached.
+    * ``<group_name>``: The name of the workspace group in which the
+      Stage is attached.
+
+    Remarks
+    -------
+    * The ``RECURSIVE`` clause indicates that the specified folder
+      is deleted recursively.
+
+    Example
+    -------
+    The following command recursively deletes a folder from a Stage
+    attached to a workspace group named **wsg1**::
+
+        DROP STAGE FOLDER '/data/' IN GROUP 'wsg1' RECURSIVE;
+
+    See Also
+    --------
+    * ``DROP STAGE FILE``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         wg = get_workspace_group(params)
@@ -229,7 +433,9 @@ DropStageFolderHandler.register(overwrite=True)
 
 class CreateStageFolderHandler(SQLHandler):
     """
-    CREATE STAGE FOLDER stage_path [ in_group ] [ overwrite ];
+    CREATE STAGE FOLDER stage_path
+        [ in_group ]
+        [ overwrite ];
 
     # Workspace group
     in_group = IN GROUP { group_id | group_name }
@@ -246,6 +452,33 @@ class CreateStageFolderHandler(SQLHandler):
     # Should an existing folder be overwritten?
     overwrite = OVERWRITE
 
+    Description
+    -----------
+    Creates a new folder at the specified path in a Stage.
+
+    Arguments
+    ---------
+    * ``<stage_path>``: The path in a Stage where the folder
+      is created. The path must end with a trailing slash (/).
+    * ``<group_id>``: The ID of the workspace group in which
+      the Stage is attached.
+    * ``<group_name>``: The name of the workspace group in
+      which the Stage is attached.
+
+    Remarks
+    -------
+    * If the ``OVERWRITE`` clause is specified, any existing
+      folder at the specified path is overwritten.
+    * The ``IN GROUP`` clause specifies the ID or the name of
+      the workspace group in which the Stage is attached.
+
+    Example
+    -------
+    The following command creates a folder in a Stage attached
+    to a workspace group named **wsg1**::
+
+        CREATE STAGE FOLDER `/data/csv/` IN GROUP 'wsg1';
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]: