Add comments explaining host defaults and password handling

pgcli/main.py

@@ -33,7 +33,9 @@ from psycopg2 import OperationalError
 _logger = logging.getLogger(__name__)
 
 @click.command()
-@click.option('-h', '--host', default='localhost', envvar='PGHOST',
+
+# Default host is '' so psycopg2 can default to either localhost or unix socket
+@click.option('-h', '--host', default='', envvar='PGHOST',
         help='Host address of the postgres database.')
 @click.option('-p', '--port', default=5432, help='Port number at which the '
         'postgres instance is listening.', envvar='PGPORT')
@@ -59,10 +61,17 @@ def cli(database, user, host, port, prompt_passwd, never_prompt):
         port = parsed.port
         host = parsed.hostname
 
+    # Prompt for a password immediately if requested via the -W flag. This
+    # avoids wasting time trying to connect to the database and catching a
+    # no-password exception.
+    # If we successfully parsed a password from a URI, there's no need to prompt
+    # for it, even with the -W flag
     if prompt_passwd and not passwd:
         passwd = click.prompt('Password', hide_input=True, show_default=False,
                 type=str)
 
+    # Prompt for a password after 1st attempt to connect without a password
+    # fails. Don't prompt if the -w flag is supplied
     auto_passwd_prompt = not passwd and not never_prompt
 
     from pgcli import __file__ as package_root
@@ -89,7 +98,10 @@ def cli(database, user, host, port, prompt_passwd, never_prompt):
             '\thost: %r'
             '\tport: %r', database, user, passwd, host, port)
 
-    # Connect to the database.
+    # Attempt to connect to the database.
+    # Note that passwd may be empty on the first attempt. If connection fails
+    # because of a missing password, but we're allowed to prompt for a password,
+    # (no -w flag), prompt for a passwd and try again.
     try:
         try:
             pgexecute = PGExecute(database, user, passwd, host, port)