gh-133934: Improve `.help` in the `sqlite3` CLI by tanloong · Pull Request #133935 · python/cpython · GitHub

Make .help in the sqlite3 CLI show a list of available commands, and .help <command> display help for that command. This matches the behavior of the SQLite CLI tool, though the output layout may not be exactly the same.

The new .help output looks like this:

Without arguments, list available commands

sqlite> .help 
Documented commands (type .help <command>):
===========================================
help  q  quit  version

With one command name, print help for that command

sqlite> .help help
        Usage: .help [-all] [command]
        
        Without argument, print the list of available commands.
        With a command name as argument, print help about that command.
        With more command names as arguments, only the first one is used.
sqlite> .help unknown
No help for 'unknown'

With -all or --all, print help for all commands

sqlite> .help -all
.help [-all] [command]
        Without argument, print the list of available commands.
        With a command name as argument, print help about that command.
        With more command names as arguments, only the first one is used.
.q(uit)
        Exit this program.
.version
        Show version of the runtime SQLite library.

If passed with two or more arguments, only use the first one

sqlite> .help version unknown
        Usage: .version
        
        Show version of the runtime SQLite library.
sqlite> .help unknown version
No help for 'unknown'

Issue: Improve .help in the sqlite3 CLI #133934

Make `.help` print list of available commands and `.help <command>` prints help for that command

Please use print( ... , file=sys.XXX) and not self.write, you must have not noticed the confusion it caused on your previous pr. You have made a mess with the color logic, with "helper" functions, some functions now using it and some not.

There is also a lot of duplication now with unnecessary PS1/2 definitions etc.

Hi @StanFromIreland , thank you for your review!

use print( ... , file=sys.XXX)

Good point! I agree and will update the code.

You have made a mess with the color logic, with "helper" functions, some functions now using it and some not.

I'm not quite clear about which parts you find problematic. It would be very helpful if you could point out specific examples where the color logic is inconsistent or where the helper functions are misused or neglected. That way, I can address the issues precisely.

There is also a lot of duplication now with unnecessary PS1/2 definitions etc.

I have reviewed the current changes and didn't find any redundant definitions. If you could indicate the exact locations where you see this duplication, I'll take another close look and make improvements.

Thank your again for your help!

Remove these and use sys.ps1 like before, this would break current behavior.

The self.PS1 is needed by this line to get the length of plain prompt string. The length can't be obtained through sys.ps1 because sys.ps1 has surrounding control sequences for coloring.

I tested it and it doesn't break current behavior.

Suggested change

      
                    Show version of the runtime SQLite library.
          
                    Print version of the runtime SQLite library.

This is the more common way of describing this. And also this does not need a new function.

Just as explained at #133935 (comment), we do need a function here.

We should not have both. Please only keep the -- option, we could have -a too but it is unnecessary IMO

Just use print and add the theme normally IMO

Not needed?

Although it's just a one-liner we still need to put it in a function with a do_ prefix to mark it as a dot command. That way the quit command is accessible by .help.

This will change, we don't need it anyway for inter-stdlib copies

ditto

Suggested change

      
            Make ``.help`` in the :mod:`sqlite3` command-line interface print list of
          
            available commands and ``.help <command>`` prints help for that command.
          
            Make ``.help`` in the :mod:`sqlite3` command-line interface print a list of
          
            available commands and ``.help <command>`` print help for that command.

I have a feeling you overdid it. We do not want to implement an exact replica of the sqlite3 program. It only implements three commands, and none of them are absolutely necessary (you can quit by pressing Ctrl-D or Ctrl-Z). They are fine when the implementation is one-line.

But the final decision is up to @erlend-aasland.

I have a feeling you overdid it.

+1, IMO a reasonable approach would be non-intrusive and have a much lower diff.

I did not have a chance to look at this PR yet, but I'll add that we do not want to replicate the SQLite shell. When we initially added the sqlite3 CLI, we had in mind that the code would be easy to read and well commented, so it could be used as a kind of tutorial for how to use the interactive console class.

Feeling down on this in past few days. I want to explain that the goal of this PR isn't to replicate sqlite3's .help. When I said “this matches the behavior of the SQLite CLI tool,” I meant to show that the .help design in this PR is reasonable. I was worried that the PR might get rejected because people thought the .help design was self-opinioned. The goal is to make .help more helpful, we may have more dot commands in the future and need to list them to users at that time.

Currently we have just 3 simple commands (none of them are strictly necessary). Their implementation takes like 13 lines. This PR doubles the size of __main__.py. It improves .help, but it was not necessary, and it spends too much code for this.

If we had 20 commands, with arguments, then this would be the right way.

Another approach to implementing this, #135224, has been merged.

tanloong added 2 commits May 12, 2025 23:03

Improve .help in sqlite3 CLI

8500c98

Make `.help` print list of available commands and `.help <command>` prints help for that command

Add news entry

b28f24f

bedevere-app Bot mentioned this pull request May 12, 2025

Improve .help in the sqlite3 CLI #133934

Closed

Fix news entry typo

8dab230

tanloong marked this pull request as ready for review May 12, 2025 15:09

tanloong requested review from berkerpeksag and erlend-aasland as code owners May 12, 2025 15:09

bedevere-app Bot added the awaiting review label May 12, 2025

StanFromIreland requested changes May 12, 2025

View reviewed changes

bedevere-app Bot added awaiting core review and removed awaiting review labels May 12, 2025

StanFromIreland reviewed May 12, 2025

View reviewed changes

serhiy-storchaka reviewed May 25, 2025

View reviewed changes

tanloong closed this Jun 23, 2025

+                          self._print_commands(self.undoc_header, cmds_undoc, 80)
+                      else:
+                          arg = arg.split()[0]
+                          if arg in ("-all", "--all"):

+                              if (method := getattr(self, "do_" + arg, None)) is not None:
+                                  print(self._help_message_from_doc(method.__doc__))
+                              else:
+                                  self._error(f"No help for '{arg}'")

+                  def do_quit(self, _):
+                      """.q(uit)
+                      Exit this program.
+                      """
+                      sys.exit(0)

+                      Each column is only as wide as necessary.
+                      Columns are separated by two spaces (one was not legible enough).
+                      """
+                      # copied and modified from Lib/cmd.py#L359

+                  def do_version(self, _):
+                      """.version
+                      Show version of the runtime SQLite library.

	Show version of the runtime SQLite library.
	Print version of the runtime SQLite library.

+                  do_q = do_quit
+                  def _help_message_from_doc(self, doc):
+                      # copied from Lib/pdb.py#L2544

+                      self.write(f"{t.message}{msg}{t.reset}\n")
+                  def _print_commands(self, header, cmds, maxcol):
+                      # copied and modified from Lib/cmd.py#L351

		Make ``.help`` in the :mod:`sqlite3` command-line interface print list of
		available commands and ``.help <command>`` prints help for that command.

		PS1 = "sqlite> "
		PS2 = " ... "

gh-133934: Improve `.help` in the `sqlite3` CLI by tanloong · Pull Request #133935 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-133934: Improve .help in the sqlite3 CLI - #133935

gh-133934: Improve .help in the sqlite3 CLI#133935tanloong wants to merge 3 commits intopython:mainpython/cpython:mainfrom tanloong:sqlite3-cli-help-more-helpfultanloong/cpython:sqlite3-cli-help-more-helpfulCopy head branch name to clipboard

Conversation

tanloong commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

tanloong commented May 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tanloong May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka commented May 12, 2025

Uh oh!

StanFromIreland commented May 12, 2025

Uh oh!

erlend-aasland commented May 12, 2025

Uh oh!

tanloong commented May 25, 2025

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

StanFromIreland commented Jun 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gh-133934: Improve .help in the sqlite3 CLI#133935
tanloong wants to merge 3 commits into
python:mainfrom
tanloong:sqlite3-cli-help-more-helpful

tanloong commented May 12, 2025 •
edited
Loading

tanloong May 25, 2025 •
edited
Loading