diff --git a/changelog.md b/changelog.md index 36cb9bc4..c4c87b3e 100644 --- a/changelog.md +++ b/changelog.md @@ -16,6 +16,7 @@ Bug Fixes Documentation -------- * Add some links to `README.md` and format compatible servers with bullets. +* Squeeze inline `/help` table width down to 110 characters. Internal diff --git a/mycli/client_commands.py b/mycli/client_commands.py index 718ce520..9057b6cd 100644 --- a/mycli/client_commands.py +++ b/mycli/client_commands.py @@ -121,7 +121,7 @@ def register_special_commands(self) -> None: self.manual_reconnect, "connect", "/connect [database]", - "Reconnect to the server, optionally switching databases.", + "Reconnect to server, optionally switching dbs.", case_sensitive=True, aliases=[SpecialCommandAlias("\\r", case_sensitive=True)], completion_snippet='reconnect to server', @@ -130,7 +130,7 @@ def register_special_commands(self) -> None: self.rehash, "rehash", "/rehash", - "Refresh auto-completions.", + "Refresh completions.", arg_type=ArgType.NO_ARGUMENT, aliases=[SpecialCommandAlias("\\#", case_sensitive=False)], completion_snippet='refresh completions', @@ -139,25 +139,25 @@ def register_special_commands(self) -> None: self.change_table_format, "tableformat", "/tableformat ", - "Change the table format used to output interactive results.", + "Set table format used for interactive results.", case_sensitive=True, aliases=[SpecialCommandAlias("\\T", case_sensitive=True)], - completion_snippet='change interactive output format', + completion_snippet='set interactive output format', ) special.register_special_command( self.change_redirect_format, "redirectformat", "/redirectformat ", - "Change the table format used to output redirected results.", + "Set table format used for redirected results.", case_sensitive=True, aliases=[SpecialCommandAlias("\\Tr", case_sensitive=True)], - completion_snippet='change redirected output format', + completion_snippet='set redirected output format', ) special.register_special_command( self.execute_from_file, "source", "/source [options] ", - "Execute queries from a file.", + "Execute queries from file.", aliases=[SpecialCommandAlias("\\.", case_sensitive=False)], completion_snippet='execute queries from file', ) @@ -165,16 +165,16 @@ def register_special_commands(self) -> None: self.change_prompt_format, "prompt", "/prompt [string]", - "Show or change prompt format.", + "Set or show prompt format.", case_sensitive=True, aliases=[SpecialCommandAlias("\\R", case_sensitive=True)], - completion_snippet='show or change prompt format', + completion_snippet='set prompt format', ) special.register_special_command( self.config_command, r'\config', - '/config [key]', - 'Inspect settings from config files.', + '/config [key]', + 'Inspect config file settings (/config help).', completion_snippet='inspect config file settings', ) diff --git a/mycli/packages/special/dbcommands.py b/mycli/packages/special/dbcommands.py index c2855dda..e61f8382 100644 --- a/mycli/packages/special/dbcommands.py +++ b/mycli/packages/special/dbcommands.py @@ -83,7 +83,7 @@ def list_databases(cur: Cursor, **_) -> list[SQLResult]: @special_command( r'\ping', '/ping', - 'Check the connection.', + 'Check connection.', arg_type=ArgType.PARSED_QUERY, completion_snippet='check connection', ) @@ -101,7 +101,7 @@ def ping(cur: Cursor, arg: str | None = None, **_) -> list[SQLResult]: @special_command( "status", "/status", - "Get status information from the server.", + "Get status information from server.", arg_type=ArgType.RAW_QUERY, case_sensitive=True, aliases=[SpecialCommandAlias("\\s", case_sensitive=True)], diff --git a/mycli/packages/special/iocommands.py b/mycli/packages/special/iocommands.py index d9eaf8c2..f186eff8 100644 --- a/mycli/packages/special/iocommands.py +++ b/mycli/packages/special/iocommands.py @@ -142,7 +142,7 @@ def disable_show_warnings() -> Generator[SQLResult, None, None]: @special_command( "pager", "/pager [command]", - "Set pager to [command]. Print query results via pager.", + "Set pager to [command]; print results via pager.", arg_type=ArgType.PARSED_QUERY, case_sensitive=True, aliases=[SpecialCommandAlias("\\P", case_sensitive=True)], @@ -181,7 +181,7 @@ def disable_pager() -> list[SQLResult]: @special_command( "\\timing", "/timing", - "Toggle timing of queries.", + "Toggle query timing.", arg_type=ArgType.NO_ARGUMENT, case_sensitive=True, aliases=[SpecialCommandAlias("\\t", case_sensitive=True)], @@ -358,7 +358,7 @@ def set_redirect(command_part: str | None, file_operator_part: str | None, file_ @special_command( r'\favorite', '/favorite ', - 'Alternative favorite query interface. See /favorite help.', + 'Manage favorite queries (/favorite help).', arg_type=ArgType.PARSED_QUERY, case_sensitive=False, completion_snippet='manage favorite queries', @@ -413,8 +413,8 @@ def favorite(arg: str, cur: Cursor | None = None, **_) -> Iterable[SQLResult]: @special_command( "\\f", - "/f [name [args..] [--key=value]]", - "List or execute favorite queries.", + "/f [name [args] [--key=val]]", + "Run favorite query shortcut.", arg_type=ArgType.PARSED_QUERY, case_sensitive=True, completion_snippet='list or run favorite queries', @@ -588,8 +588,8 @@ def subst_favorite_query_args(query: str, args: list[str]) -> list[str | None]: @special_command( "\\fs", "/fs ", - "Save a favorite query.", - completion_snippet='save favorite queries', + "Save favorite query shortcut.", + completion_snippet='save favorite query', ) def save_favorite_query(arg: str, **_) -> list[SQLResult]: """Save a new favorite query.""" @@ -643,8 +643,8 @@ def is_favorite_save_command(statement: str) -> bool: @special_command( "\\fd", "/fd ", - "Delete a favorite query.", - completion_snippet='delete favorite queries', + "Delete favorite query shortcut.", + completion_snippet='delete favorite query', ) def delete_favorite_query(arg: str, **_) -> list[SQLResult]: """Delete an existing favorite query.""" @@ -663,8 +663,8 @@ def _delete_favorite_query(arg: str, usage: str) -> list[SQLResult]: @special_command( r'\dsn', - '/dsn ', - 'Manage saved DSNs. See /dsn help.', + '/dsn ', + 'Manage saved DSNs (/dsn help).', arg_type=ArgType.PARSED_QUERY, case_sensitive=False, completion_snippet='manage saved DSNs', @@ -743,8 +743,8 @@ def _edit_dsn_alias(alias: str) -> list[SQLResult]: @special_command( "system", "/system [-r] ", - "Execute a system shell command (raw mode with -r).", - completion_snippet='execute system command', + "Execute shell command (-r for raw mode).", + completion_snippet='execute shell command', ) def execute_system_command(arg: str, **_) -> list[SQLResult]: """Execute a system shell command.""" @@ -826,7 +826,7 @@ def parseargfile(arg: str) -> tuple[str, str]: @special_command( "tee", "/tee [-o] ", - "Append all results to an output file (overwrite using -o).", + "Append all results to file (-o to overwrite).", completion_snippet='append all results to file', ) def set_tee(arg: str, **_) -> list[SQLResult]: @@ -850,7 +850,7 @@ def close_tee() -> None: @special_command( "notee", "/notee", - "Stop writing results to an output file.", + "Stop writing all results to tee file.", completion_snippet='stop writing to tee file', ) def no_tee(arg: str, **_) -> list[SQLResult]: @@ -871,9 +871,9 @@ def write_tee(output: str | ANSI | FormattedText, nl: bool = True) -> None: @special_command( "\\once", "/once [-o] ", - "Append next result to an output file (overwrite using -o).", + "Append next result to a file (-o to overwrite).", aliases=[SpecialCommandAlias("\\o", case_sensitive=False)], - completion_snippet='append one result to file', + completion_snippet='append next result to file', ) def set_once(arg: str, **_) -> list[SQLResult]: global once_file, written_to_once_file @@ -935,9 +935,9 @@ def _run_post_redirect_hook(post_redirect_command: str, filename: str) -> None: @special_command( "\\pipe_once", "/pipe_once ", - "Send next result to a subprocess.", + "Send next result to subprocess.", aliases=[SpecialCommandAlias("\\|", case_sensitive=False)], - completion_snippet='send one result to subprocess', + completion_snippet='next result to subprocess', ) def set_pipe_once(arg: str, **_) -> list[SQLResult]: if not arg: @@ -999,14 +999,14 @@ def flush_pipe_once_if_written(post_redirect_command: str) -> None: @special_command( "watch", - "/watch [seconds] [-c] ", - "Execute query every [seconds] seconds (5 by default).", + "/watch [sec] [-c] ", + "Execute query every [sec] seconds (default 5).", completion_snippet='run query every N seconds', ) def watch_query(arg: str, **kwargs) -> Generator[SQLResult, None, None]: - usage = """Syntax: watch [seconds] [-c] query. - * seconds: The interval at the query will be repeated, in seconds. - By default 5. + usage = """Syntax: watch [sec] [-c] query. + * sec: The interval at the query will be repeated, in seconds. + By default: 5. * -c: Clears the screen between every iteration. """ if not arg: @@ -1072,8 +1072,8 @@ def watch_query(arg: str, **kwargs) -> Generator[SQLResult, None, None]: @special_command( "delimiter", "/delimiter ", - "Change end-of-statement delimiter.", - completion_snippet='change end-of-statement delimiter', + "Set end-of-statement delimiter.", + completion_snippet='set end-of-statement delimiter', ) def set_delimiter(arg: str, **_) -> list[SQLResult]: return delimiter_command.set(arg) diff --git a/mycli/packages/special/main.py b/mycli/packages/special/main.py index 471f0434..7fb58b66 100644 --- a/mycli/packages/special/main.py +++ b/mycli/packages/special/main.py @@ -231,13 +231,13 @@ def execute(cur: Cursor, sql: str) -> list[SQLResult]: @special_command( "help", "/help [term]", - "Show this table, or search for help on a term.", + "Show this table, or search for help on term.", arg_type=ArgType.NO_ARGUMENT, aliases=[SpecialCommandAlias("\\?", case_sensitive=False), SpecialCommandAlias("?", case_sensitive=False)], completion_snippet='show help or search', ) def show_help(*_args) -> list[SQLResult]: - header = ["Command", "Shortcut", "Usage", "Description"] + header = ["Command", "Alias", "Usage", "Description"] result = [] for _, value in sorted(COMMANDS.items(), key=lambda x: str.casefold(x[0].removeprefix('\\').removeprefix('/'))): @@ -300,9 +300,9 @@ def show_keyword_help(cur: Cursor, arg: str) -> list[SQLResult]: @special_command( '\\bug', '/bug', - 'File a bug on GitHub.', + 'File bug on GitHub.', arg_type=ArgType.NO_ARGUMENT, - completion_snippet='file a bug on GitHub', + completion_snippet='file bug on GitHub', ) def file_bug(*_args) -> list[SQLResult]: webbrowser.open_new_tab(ISSUES_URL) @@ -332,7 +332,7 @@ def quit_(*_args): @special_command( "\\edit", "/edit | \\edit", - "Edit query with editor (uses $VISUAL or $EDITOR).", + "Edit query with editor (via $VISUAL/$EDITOR).", arg_type=ArgType.NO_ARGUMENT, case_sensitive=True, aliases=[SpecialCommandAlias("\\e", case_sensitive=True)], @@ -341,7 +341,7 @@ def quit_(*_args): @special_command( "\\clip", "/clip | \\clip", - "Copy query to the system clipboard.", + "Copy query to system clipboard.", arg_type=ArgType.NO_ARGUMENT, case_sensitive=True, completion_snippet='copy query to clipboard', @@ -349,7 +349,7 @@ def quit_(*_args): @special_command( "\\G", "\\G", - "Display query results vertically.", + "Display results vertically.", arg_type=ArgType.NO_ARGUMENT, case_sensitive=True, backslash_only=True, @@ -357,7 +357,7 @@ def quit_(*_args): @special_command( "\\g", "\\g", - "Display query results (mnemonic: go).", + "Display results (mnemonic: go).", arg_type=ArgType.NO_ARGUMENT, case_sensitive=True, backslash_only=True, @@ -365,7 +365,7 @@ def quit_(*_args): @special_command( "\\x", "\\x", - "Display query results in an explorer rather than a pager.", + "Display results in an interactive explorer.", arg_type=ArgType.NO_ARGUMENT, case_sensitive=True, backslash_only=True, @@ -379,11 +379,11 @@ def stub(): @special_command( "\\llm", "/llm [arguments]", - "Interrogate an LLM. See \"/llm help\".", + "Interrogate LLM (/llm help).", arg_type=ArgType.RAW_QUERY, case_sensitive=True, aliases=[SpecialCommandAlias("\\ai", case_sensitive=True)], - completion_snippet='interrogate an LLM', + completion_snippet='interrogate LLM', ) def llm_stub(): raise NotImplementedError diff --git a/test/features/fixture_data/help_commands.txt b/test/features/fixture_data/help_commands.txt index e3ec62e6..c2fdbd4c 100644 --- a/test/features/fixture_data/help_commands.txt +++ b/test/features/fixture_data/help_commands.txt @@ -1,43 +1,43 @@ -+-----------------+----------+----------------------------------------+-------------------------------------------------------------+ -| Command | Shortcut | Usage | Description | -+-----------------+----------+----------------------------------------+-------------------------------------------------------------+ -| /bug | | /bug | File a bug on GitHub. | -| /clip | | /clip | \clip | Copy query to the system clipboard. | -| /config | | /config [key] | Inspect settings from config files. | -| /connect | /r | /connect [database] | Reconnect to the server, optionally switching databases. | -| /delimiter | | /delimiter | Change end-of-statement delimiter. | -| /dsn | | /dsn | Manage saved DSNs. See /dsn help. | -| /dt | | /dt[+] [table] | List or describe tables. | -| /edit | /e | /edit | \edit | Edit query with editor (uses $VISUAL or $EDITOR). | -| /exit | /q | /exit | Exit. | -| /f | | /f [name [args..] [--key=value]] | List or execute favorite queries. | -| /favorite | | /favorite | Alternative favorite query interface. See /favorite help. | -| /fd | | /fd | Delete a favorite query. | -| /fs | | /fs | Save a favorite query. | -| \g | | \g | Display query results (mnemonic: go). | -| \G | | \G | Display query results vertically. | -| /help | /? | /help [term] | Show this table, or search for help on a term. | -| /l | | /l | List databases. | -| /llm | /ai | /llm [arguments] | Interrogate an LLM. See "/llm help". | -| /nopager | /n | /nopager | Disable pager; print to stdout. | -| /notee | | /notee | Stop writing results to an output file. | -| /nowarnings | /w | /nowarnings | Disable automatic warnings display. | -| /once | /o | /once [-o] | Append next result to an output file (overwrite using -o). | -| /pager | /P | /pager [command] | Set pager to [command]. Print query results via pager. | -| /ping | | /ping | Check the connection. | -| /pipe_once | /| | /pipe_once | Send next result to a subprocess. | -| /prompt | /R | /prompt [string] | Show or change prompt format. | -| /quit | /q | /quit | Quit. | -| /redirectformat | /Tr | /redirectformat | Change the table format used to output redirected results. | -| /rehash | /# | /rehash | Refresh auto-completions. | -| /source | /. | /source [options] | Execute queries from a file. | -| /status | /s | /status | Get status information from the server. | -| /system | | /system [-r] | Execute a system shell command (raw mode with -r). | -| /tableformat | /T | /tableformat | Change the table format used to output interactive results. | -| /tee | | /tee [-o] | Append all results to an output file (overwrite using -o). | -| /timing | /t | /timing | Toggle timing of queries. | -| /use | /u | /use | Change to a new database. | -| /warnings | /W | /warnings | Enable automatic warnings display. | -| /watch | | /watch [seconds] [-c] | Execute query every [seconds] seconds (5 by default). | -| \x | | \x | Display query results in an explorer rather than a pager. | -+-----------------+----------+----------------------------------------+-------------------------------------------------------------+ ++-----------------+--------+------------------------------+--------------------------------------------------+ +| Command | Alias | Usage | Description | ++-----------------+--------+------------------------------+--------------------------------------------------+ +| /bug | | /bug | File bug on GitHub. | +| /clip | | /clip | \clip | Copy query to system clipboard. | +| /config | | /config [key] | Inspect config file settings (/config help). | +| /connect | /r | /connect [database] | Reconnect to server, optionally switching dbs. | +| /delimiter | | /delimiter | Set end-of-statement delimiter. | +| /dsn | | /dsn | Manage saved DSNs (/dsn help). | +| /dt | | /dt[+] [table] | List or describe tables. | +| /edit | /e | /edit | \edit | Edit query with editor (via $VISUAL/$EDITOR). | +| /exit | /q | /exit | Exit. | +| /f | | /f [name [args] [--key=val]] | Run favorite query shortcut. | +| /favorite | | /favorite | Manage favorite queries (/favorite help). | +| /fd | | /fd | Delete favorite query shortcut. | +| /fs | | /fs | Save favorite query shortcut. | +| \g | | \g | Display results (mnemonic: go). | +| \G | | \G | Display results vertically. | +| /help | /? | /help [term] | Show this table, or search for help on term. | +| /l | | /l | List databases. | +| /llm | /ai | /llm [arguments] | Interrogate LLM (/llm help). | +| /nopager | /n | /nopager | Disable pager; print to stdout. | +| /notee | | /notee | Stop writing all results to tee file. | +| /nowarnings | /w | /nowarnings | Disable automatic warnings display. | +| /once | /o | /once [-o] | Append next result to a file (-o to overwrite). | +| /pager | /P | /pager [command] | Set pager to [command]; print results via pager. | +| /ping | | /ping | Check connection. | +| /pipe_once | /| | /pipe_once | Send next result to subprocess. | +| /prompt | /R | /prompt [string] | Set or show prompt format. | +| /quit | /q | /quit | Quit. | +| /redirectformat | /Tr | /redirectformat | Set table format used for redirected results. | +| /rehash | /# | /rehash | Refresh completions. | +| /source | /. | /source [options] | Execute queries from file. | +| /status | /s | /status | Get status information from server. | +| /system | | /system [-r] | Execute shell command (-r for raw mode). | +| /tableformat | /T | /tableformat | Set table format used for interactive results. | +| /tee | | /tee [-o] | Append all results to file (-o to overwrite). | +| /timing | /t | /timing | Toggle query timing. | +| /use | /u | /use | Change to a new database. | +| /warnings | /W | /warnings | Enable automatic warnings display. | +| /watch | | /watch [sec] [-c] | Execute query every [sec] seconds (default 5). | +| \x | | \x | Display results in an interactive explorer. | ++-----------------+--------+------------------------------+--------------------------------------------------+ diff --git a/test/pytests/test_client_commands.py b/test/pytests/test_client_commands.py index 322c71ca..24d70469 100644 --- a/test/pytests/test_client_commands.py +++ b/test/pytests/test_client_commands.py @@ -122,12 +122,12 @@ def test_register_special_commands_registers_expected_commands(monkeypatch: pyte assert calls[5][0] == client.execute_from_file assert calls[5][2:4] == ( '/source [options] ', - 'Execute queries from a file.', + 'Execute queries from file.', ) assert calls[6][0] == client.change_prompt_format - assert calls[6][2:4] == ('/prompt [string]', 'Show or change prompt format.') + assert calls[6][2:4] == ('/prompt [string]', 'Set or show prompt format.') assert calls[7][0] == client.config_command - assert calls[7][2:4] == ('/config [key]', 'Inspect settings from config files.') + assert calls[7][2:4] == ('/config [key]', 'Inspect config file settings (/config help).') def test_rehash_refreshes_frecency_and_completions(monkeypatch: pytest.MonkeyPatch) -> None: diff --git a/test/pytests/test_special_dbcommands.py b/test/pytests/test_special_dbcommands.py index d92ffd5f..d506ae27 100644 --- a/test/pytests/test_special_dbcommands.py +++ b/test/pytests/test_special_dbcommands.py @@ -225,7 +225,7 @@ def test_ping_command_registration() -> None: assert command.handler is ping assert command.usage == '/ping' - assert command.description == 'Check the connection.' + assert command.description == 'Check connection.' assert command.completion_snippet == 'check connection' assert special_main.COMMANDS['/ping'].handler is ping diff --git a/test/pytests/test_special_iocommands.py b/test/pytests/test_special_iocommands.py index ba29c272..4285272d 100644 --- a/test/pytests/test_special_iocommands.py +++ b/test/pytests/test_special_iocommands.py @@ -297,9 +297,7 @@ def test_special_favorite_query(favorite_queries_instance) -> None: with db_connection().cursor() as cur: query = r'\?' mycli.packages.special.execute(cur, rf"\fs special {query}") - assert (r'\G', None, r'\G', 'Display query results vertically.') in next( - mycli.packages.special.execute(cur, r'\f special') - ).rows + assert (r'\G', None, r'\G', 'Display results vertically.') in next(mycli.packages.special.execute(cur, r'\f special')).rows def test_once_command(): diff --git a/test/pytests/test_special_main.py b/test/pytests/test_special_main.py index cd1b371a..861b0594 100644 --- a/test/pytests/test_special_main.py +++ b/test/pytests/test_special_main.py @@ -355,7 +355,7 @@ def test_show_help_lists_only_visible_commands(restore_commands: None) -> None: result = special_main.show_help()[0] - assert result.header == ['Command', 'Shortcut', 'Usage', 'Description'] + assert result.header == ['Command', 'Alias', 'Usage', 'Description'] assert result.rows == [('/visible', '/v', '/visible', 'Visible command')] assert f'Docs index — {DOCS_URL}' in result.postamble @@ -379,7 +379,7 @@ def test_show_keyword_help_for_case_sensitive_special_alias() -> None: assert result.rows == [ ( r'/e', - '/edit | \\edit\nEdit query with editor (uses $VISUAL or $EDITOR).', + '/edit | \\edit\nEdit query with editor (via $VISUAL/$EDITOR).', '', ) ]