pgcli 4.0.1__tar.gz → 4.2.0__tar.gz

{pgcli-4.0.1 → pgcli-4.2.0}/AUTHORS

@@ -130,6 +130,14 @@ Contributors:
     * blag
     * Rob Berry (rob-b)
     * Sharon Yogev (sharonyogev)
+    * Hollis Wu (holi0317)
+    * Antonio Aguilar (crazybolillo)
+    * Andrew M. MacFie (amacfie)
+    * saucoide
+    * Chris Rose (offbyone/offby1)
+    * Mathieu Dupuy (deronnax)
+    * Chris Novakovic
+    * Josh Lynch (josh-lynch)
 
 Creator:
 --------

{pgcli-4.0.1/pgcli.egg-info → pgcli-4.2.0}/PKG-INFO

@@ -1,39 +1,39 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pgcli
-Version: 4.0.1
+Version: 4.2.0
 Summary: CLI for Postgres Database. With auto-completion and syntax highlighting.
-Home-page: http://pgcli.com
-Author: Pgcli Core Team
-Author-email: pgcli-dev@googlegroups.com
+Author-email: Pgcli Core Team <pgcli-dev@googlegroups.com>
 License: BSD
+Project-URL: Homepage, https://pgcli.com
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: Unix
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: SQL
 Classifier: Topic :: Database
 Classifier: Topic :: Database :: Front-Ends
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 License-File: AUTHORS
 Requires-Dist: pgspecial>=2.0.0
 Requires-Dist: click>=4.1
 Requires-Dist: Pygments>=2.0
 Requires-Dist: prompt_toolkit<4.0.0,>=2.0.6
-Requires-Dist: psycopg>=3.0.14
-Requires-Dist: sqlparse<0.5,>=0.3.0
+Requires-Dist: psycopg>=3.0.14; sys_platform != "win32"
+Requires-Dist: psycopg-binary>=3.0.14; sys_platform == "win32"
+Requires-Dist: sqlparse<0.6,>=0.3.0
 Requires-Dist: configobj>=5.0.6
-Requires-Dist: pendulum>=2.1.0
 Requires-Dist: cli_helpers[styles]>=2.2.1
-Requires-Dist: setproctitle>=1.1.9
+Requires-Dist: setproctitle>=1.1.9; sys_platform != "win32" and "CYGWIN" not in sys_platform
 Provides-Extra: keyring
 Requires-Dist: keyring>=12.2.0; extra == "keyring"
 Provides-Extra: sshtunnel
@@ -220,7 +220,7 @@ Alternatively, you can install ``pgcli`` as a python package using a package
 manager called called ``pip``. You will need postgres installed on your system
 for this to work.
 
-In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installing.html.
+In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installation/
 
 ::
 
@@ -250,7 +250,7 @@ If pip is not installed check if easy_install is available on the system.
 Linux:
 ======
 
-In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installing.html.
+In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installation/
 
 Check if pip is already available in your system.
 
@@ -393,7 +393,10 @@ choice:
 
     In [3]: my_result = _
 
-Pgcli dropped support for Python<3.8 as of 4.0.0. If you need it, install ``pgcli <= 4.0.0``.
+Pgcli dropped support for:
+
+* Python<3.8 as of 4.0.0.
+* Python<3.9 as of 4.2.0.
 
 Thanks:
 -------

{pgcli-4.0.1 → pgcli-4.2.0}/README.rst

@@ -179,7 +179,7 @@ Alternatively, you can install ``pgcli`` as a python package using a package
 manager called called ``pip``. You will need postgres installed on your system
 for this to work.
 
-In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installing.html.
+In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installation/
 
 ::
 
@@ -209,7 +209,7 @@ If pip is not installed check if easy_install is available on the system.
 Linux:
 ======
 
-In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installing.html.
+In depth getting started guide for ``pip`` - https://pip.pypa.io/en/latest/installation/
 
 Check if pip is already available in your system.
 
@@ -352,7 +352,10 @@ choice:
 
     In [3]: my_result = _
 
-Pgcli dropped support for Python<3.8 as of 4.0.0. If you need it, install ``pgcli <= 4.0.0``.
+Pgcli dropped support for:
+
+* Python<3.8 as of 4.0.0.
+* Python<3.9 as of 4.2.0.
 
 Thanks:
 -------

{pgcli-4.0.1 → pgcli-4.2.0}/changelog.rst

@@ -1,5 +1,44 @@
+4.2.0 (2025-03-06)
 ==================
-4.0.1 (2023-11-30)
+
+Features
+--------
+* Add a `--ping` command line option; allows pgcli to replace `pg_isready`
+* Changed the packaging metadata from setup.py to pyproject.toml
+
+Bug fixes:
+----------
+* Avoid raising `NameError` when exiting unsuccessfully in some cases
+* Use configured `alias_map_file` to generate table aliases if available.
+
+Internal:
+---------
+
+* Drop support for Python 3.8 and add 3.13.
+
+4.1.0 (2024-03-09)
+==================
+
+Features:
+---------
+* Support `PGAPPNAME` as an environment variable and `--application-name` as a command line argument.
+* Add `verbose_errors` config and `\v` special command which enable the
+  displaying of all Postgres error fields received.
+* Show Postgres notifications.
+* Support sqlparse 0.5.x
+* Add `--log-file [filename]` cli argument and `\log-file [filename]` special commands to
+  log to an external file in addition to the normal output
+
+Bug fixes:
+----------
+
+* Fix display of "short host" in prompt (with `\h`) for IPv4 addresses ([issue 964](https://github.com/dbcli/pgcli/issues/964)).
+* Fix backwards display of NOTICEs from a Function ([issue 1443](https://github.com/dbcli/pgcli/issues/1443))
+* Fix psycopg errors when installing on Windows.  ([issue 1413](https://https://github.com/dbcli/pgcli/issues/1413))
+* Use a home-made function to display query duration instead of relying on a third-party library (the general behaviour does not change), which fixes the installation of `pgcli` on 32-bit architectures ([issue 1451](https://github.com/dbcli/pgcli/issues/1451))
+
+==================
+4.0.1 (2023-10-30)
 ==================
 
 Internal:
@@ -7,7 +46,7 @@ Internal:
 * Allow stable version of pendulum.
 
 ==================
-4.0.0 (2023-11-27)
+4.0.0 (2023-10-27)
 ==================
 
 Features:

pgcli-4.2.0/pgcli/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.2.0"

{pgcli-4.0.1 → pgcli-4.2.0}/pgcli/main.py

@@ -11,9 +11,9 @@ import logging
 import threading
 import shutil
 import functools
-import pendulum
 import datetime as dt
 import itertools
+import pathlib
 import platform
 from time import time, sleep
 from typing import Optional
@@ -74,8 +74,9 @@ from urllib.parse import urlparse
 
 from getpass import getuser
 
-from psycopg import OperationalError, InterfaceError
+from psycopg import OperationalError, InterfaceError, Notify
 from psycopg.conninfo import make_conninfo, conninfo_to_dict
+from psycopg.errors import Diagnostic
 
 from collections import namedtuple
 
@@ -129,6 +130,15 @@ class PgCliQuitError(Exception):
     pass
 
 
+def notify_callback(notify: Notify):
+    click.secho(
+        'Notification received on channel "{}" (PID {}):\n{}'.format(
+            notify.channel, notify.pid, notify.payload
+        ),
+        fg="green",
+    )
+
+
 class PGCli:
     default_prompt = "\\u@\\h:\\d> "
     max_len_prompt = 30
@@ -165,6 +175,7 @@ class PGCli:
         pgexecute=None,
         pgclirc_file=None,
         row_limit=None,
+        application_name="pgcli",
         single_connection=False,
         less_chatty=None,
         prompt=None,
@@ -172,6 +183,7 @@ class PGCli:
         auto_vertical_output=False,
         warn=None,
         ssh_tunnel_url: Optional[str] = None,
+        log_file: Optional[str] = None,
     ):
         self.force_passwd_prompt = force_passwd_prompt
         self.never_passwd_prompt = never_passwd_prompt
@@ -210,6 +222,8 @@ class PGCli:
         else:
             self.row_limit = c["main"].as_int("row_limit")
 
+        self.application_name = application_name
+
         # if not specified, set to DEFAULT_MAX_FIELD_WIDTH
         # if specified but empty, set to None to disable truncation
         # ellipsis will take at least 3 symbols, so this can't be less than 3 if specified and > 0
@@ -237,6 +251,9 @@ class PGCli:
         )
 
         self.less_chatty = bool(less_chatty) or c["main"].as_bool("less_chatty")
+        self.verbose_errors = "verbose_errors" in c["main"] and c["main"].as_bool(
+            "verbose_errors"
+        )
         self.null_string = c["main"].get("null_string", "<null>")
         self.prompt_format = (
             prompt
@@ -295,6 +312,11 @@ class PGCli:
         self.ssh_tunnel_url = ssh_tunnel_url
         self.ssh_tunnel = None
 
+        if log_file:
+            with open(log_file, "a+"):
+                pass  # ensure writeable
+        self.log_file = log_file
+
         # formatter setup
         self.formatter = TabularOutputFormatter(format_name=c["main"]["table_format"])
         register_new_formatter(self.formatter)
@@ -354,6 +376,12 @@ class PGCli:
             "\\o [filename]",
             "Send all query results to file.",
         )
+        self.pgspecial.register(
+            self.write_to_logfile,
+            "\\log-file",
+            "\\log-file [filename]",
+            "Log all query results to a logfile, in addition to the normal output destination.",
+        )
         self.pgspecial.register(
             self.info_connection, "\\conninfo", "\\conninfo", "Get connection details"
         )
@@ -378,6 +406,26 @@ class PGCli:
             "Echo a string to the query output channel.",
         )
 
+        self.pgspecial.register(
+            self.toggle_verbose_errors,
+            "\\v",
+            "\\v [on|off]",
+            "Toggle verbose errors.",
+        )
+
+    def toggle_verbose_errors(self, pattern, **_):
+        flag = pattern.strip()
+
+        if flag == "on":
+            self.verbose_errors = True
+        elif flag == "off":
+            self.verbose_errors = False
+        else:
+            self.verbose_errors = not self.verbose_errors
+
+        message = "Verbose errors " + "on." if self.verbose_errors else "off."
+        return [(None, None, None, message)]
+
     def echo(self, pattern, **_):
         return [(None, None, None, pattern)]
 
@@ -473,6 +521,26 @@ class PGCli:
             explain_mode=self.explain_mode,
         )
 
+    def write_to_logfile(self, pattern, **_):
+        if not pattern:
+            self.log_file = None
+            message = "Logfile capture disabled"
+            return [(None, None, None, message, "", True, True)]
+
+        log_file = pathlib.Path(pattern).expanduser().absolute()
+
+        try:
+            with open(log_file, "a+"):
+                pass  # ensure writeable
+        except OSError as e:
+            self.log_file = None
+            message = str(e) + "\nLogfile capture disabled"
+            return [(None, None, None, message, "", False, True)]
+
+        self.log_file = str(log_file)
+        message = 'Writing to file "%s"' % self.log_file
+        return [(None, None, None, message, "", True, True)]
+
     def write_to_file(self, pattern, **_):
         if not pattern:
             self.output_file = None
@@ -542,7 +610,7 @@ class PGCli:
             click.secho(
                 f"service '{service}' was not found in {file}", err=True, fg="red"
             )
-            exit(1)
+            sys.exit(1)
         self.connect(
             database=service_config.get("dbname"),
             host=service_config.get("host"),
@@ -568,7 +636,7 @@ class PGCli:
         if not database:
             database = user
 
-        kwargs.setdefault("application_name", "pgcli")
+        kwargs.setdefault("application_name", self.application_name)
 
         # If password prompt is not forced but no password is provided, try
         # getting it from environment variable.
@@ -642,7 +710,7 @@ class PGCli:
                 self.logger.handlers = logger_handlers
                 self.logger.error("traceback: %r", traceback.format_exc())
                 click.secho(str(e), err=True, fg="red")
-                exit(1)
+                sys.exit(1)
             self.logger.handlers = logger_handlers
 
             atexit.register(self.ssh_tunnel.stop)
@@ -658,7 +726,16 @@ class PGCli:
         # prompt for a password (no -w flag), prompt for a passwd and try again.
         try:
             try:
-                pgexecute = PGExecute(database, user, passwd, host, port, dsn, **kwargs)
+                pgexecute = PGExecute(
+                    database,
+                    user,
+                    passwd,
+                    host,
+                    port,
+                    dsn,
+                    notify_callback,
+                    **kwargs,
+                )
             except (OperationalError, InterfaceError) as e:
                 if should_ask_for_password(e):
                     passwd = click.prompt(
@@ -668,7 +745,14 @@ class PGCli:
                         type=str,
                     )
                     pgexecute = PGExecute(
-                        database, user, passwd, host, port, dsn, **kwargs
+                        database,
+                        user,
+                        passwd,
+                        host,
+                        port,
+                        dsn,
+                        notify_callback,
+                        **kwargs,
                     )
                 else:
                     raise e
@@ -679,7 +763,7 @@ class PGCli:
             self.logger.debug("Database connection failed: %r.", e)
             self.logger.error("traceback: %r", traceback.format_exc())
             click.secho(str(e), err=True, fg="red")
-            exit(1)
+            sys.exit(1)
 
         self.pgexecute = pgexecute
 
@@ -775,7 +859,7 @@ class PGCli:
         else:
             try:
                 if self.output_file and not text.startswith(
-                    ("\\o ", "\\? ", "\\echo ")
+                    ("\\o ", "\\log-file", "\\? ", "\\echo ")
                 ):
                     try:
                         with open(self.output_file, "a", encoding="utf-8") as f:
@@ -787,6 +871,23 @@ class PGCli:
                 else:
                     if output:
                         self.echo_via_pager("\n".join(output))
+
+                # Log to file in addition to normal output
+                if (
+                    self.log_file
+                    and not text.startswith(("\\o ", "\\log-file", "\\? ", "\\echo "))
+                    and not text.strip() == ""
+                ):
+                    try:
+                        with open(self.log_file, "a", encoding="utf-8") as f:
+                            click.echo(
+                                dt.datetime.now().isoformat(), file=f
+                            )  # timestamp log
+                            click.echo(text, file=f)
+                            click.echo("\n".join(output), file=f)
+                            click.echo("", file=f)  # extra newline
+                    except OSError as e:
+                        click.secho(str(e), err=True, fg="red")
             except KeyboardInterrupt:
                 pass
 
@@ -797,9 +898,9 @@ class PGCli:
                         "Time: %0.03fs (%s), executed in: %0.03fs (%s)"
                         % (
                             query.total_time,
-                            pendulum.Duration(seconds=query.total_time).in_words(),
+                            duration_in_words(query.total_time),
                             query.execution_time,
-                            pendulum.Duration(seconds=query.execution_time).in_words(),
+                            duration_in_words(query.execution_time),
                         )
                     )
                 else:
@@ -1053,7 +1154,7 @@ class PGCli:
         res = self.pgexecute.run(
             text,
             self.pgspecial,
-            exception_formatter,
+            lambda x: exception_formatter(x, self.verbose_errors),
             on_error_resume,
             explain_mode=self.explain_mode,
         )
@@ -1337,6 +1438,12 @@ class PGCli:
     type=click.INT,
     help="Set threshold for row limit prompt. Use 0 to disable prompt.",
 )
+@click.option(
+    "--application-name",
+    default="pgcli",
+    envvar="PGAPPNAME",
+    help="Application name for the connection.",
+)
 @click.option(
     "--less-chatty",
     "less_chatty",
@@ -1356,6 +1463,13 @@ class PGCli:
     is_flag=True,
     help="list available databases, then exit.",
 )
+@click.option(
+    "--ping",
+    "ping_database",
+    is_flag=True,
+    default=False,
+    help="Check database connectivity, then exit.",
+)
 @click.option(
     "--auto-vertical-output",
     is_flag=True,
@@ -1371,6 +1485,11 @@ class PGCli:
     default=None,
     help="Open an SSH tunnel to the given address and connect to the database from it.",
 )
+@click.option(
+    "--log-file",
+    default=None,
+    help="Write all queries & output into a file, in addition to the normal output destination.",
+)
 @click.argument("dbname", default=lambda: None, envvar="PGDATABASE", nargs=1)
 @click.argument("username", default=lambda: None, envvar="PGUSER", nargs=1)
 def cli(
@@ -1387,14 +1506,17 @@ def cli(
     pgclirc,
     dsn,
     row_limit,
+    application_name,
     less_chatty,
     prompt,
     prompt_dsn,
     list_databases,
+    ping_database,
     auto_vertical_output,
     list_dsn,
     warn,
     ssh_tunnel: str,
+    log_file: str,
 ):
     if version:
         print("Version:", __version__)
@@ -1429,7 +1551,7 @@ def cli(
                 err=True,
                 fg="red",
             )
-            exit(1)
+            sys.exit(1)
 
     if ssh_tunnel and not SSH_TUNNEL_SUPPORT:
         click.secho(
@@ -1438,13 +1560,14 @@ def cli(
             err=True,
             fg="red",
         )
-        exit(1)
+        sys.exit(1)
 
     pgcli = PGCli(
         prompt_passwd,
         never_prompt,
         pgclirc_file=pgclirc,
         row_limit=row_limit,
+        application_name=application_name,
         single_connection=single_connection,
         less_chatty=less_chatty,
         prompt=prompt,
@@ -1452,6 +1575,7 @@ def cli(
         auto_vertical_output=auto_vertical_output,
         warn=warn,
         ssh_tunnel_url=ssh_tunnel,
+        log_file=log_file,
     )
 
     # Choose which ever one has a valid value.
@@ -1465,8 +1589,8 @@ def cli(
         service = database[8:]
     elif os.getenv("PGSERVICE") is not None:
         service = os.getenv("PGSERVICE")
-    # because option --list or -l are not supposed to have a db name
-    if list_databases:
+    # because option --ping, --list or -l are not supposed to have a db name
+    if list_databases or ping_database:
         database = "postgres"
 
     if dsn != "":
@@ -1480,7 +1604,7 @@ def cli(
                 err=True,
                 fg="red",
             )
-            exit(1)
+            sys.exit(1)
         except Exception:
             click.secho(
                 "Invalid DSNs found in the config file. "
@@ -1488,7 +1612,7 @@ def cli(
                 err=True,
                 fg="red",
             )
-            exit(1)
+            sys.exit(1)
         pgcli.connect_uri(dsn_config)
         pgcli.dsn_alias = dsn
     elif "://" in database:
@@ -1510,6 +1634,20 @@ def cli(
 
         sys.exit(0)
 
+    if ping_database:
+        try:
+            list(pgcli.pgexecute.run("SELECT 1"))
+        except Exception:
+            click.secho(
+                "Could not connect to the database. Please check that the database is running.",
+                err=True,
+                fg="red",
+            )
+            sys.exit(1)
+        else:
+            click.echo("PONG")
+            sys.exit(0)
+
     pgcli.logger.debug(
         "Launch Params: \n" "\tdatabase: %r" "\tuser: %r" "\thost: %r" "\tport: %r",
         database,
@@ -1583,8 +1721,71 @@ def is_select(status):
     return status.split(None, 1)[0].lower() == "select"
 
 
-def exception_formatter(e):
-    return click.style(str(e), fg="red")
+def diagnostic_output(diagnostic: Diagnostic) -> str:
+    fields = []
+
+    if diagnostic.severity is not None:
+        fields.append("Severity: " + diagnostic.severity)
+
+    if diagnostic.severity_nonlocalized is not None:
+        fields.append("Severity (non-localized): " + diagnostic.severity_nonlocalized)
+
+    if diagnostic.sqlstate is not None:
+        fields.append("SQLSTATE code: " + diagnostic.sqlstate)
+
+    if diagnostic.message_primary is not None:
+        fields.append("Message: " + diagnostic.message_primary)
+
+    if diagnostic.message_detail is not None:
+        fields.append("Detail: " + diagnostic.message_detail)
+
+    if diagnostic.message_hint is not None:
+        fields.append("Hint: " + diagnostic.message_hint)
+
+    if diagnostic.statement_position is not None:
+        fields.append("Position: " + diagnostic.statement_position)
+
+    if diagnostic.internal_position is not None:
+        fields.append("Internal position: " + diagnostic.internal_position)
+
+    if diagnostic.internal_query is not None:
+        fields.append("Internal query: " + diagnostic.internal_query)
+
+    if diagnostic.context is not None:
+        fields.append("Where: " + diagnostic.context)
+
+    if diagnostic.schema_name is not None:
+        fields.append("Schema name: " + diagnostic.schema_name)
+
+    if diagnostic.table_name is not None:
+        fields.append("Table name: " + diagnostic.table_name)
+
+    if diagnostic.column_name is not None:
+        fields.append("Column name: " + diagnostic.column_name)
+
+    if diagnostic.datatype_name is not None:
+        fields.append("Data type name: " + diagnostic.datatype_name)
+
+    if diagnostic.constraint_name is not None:
+        fields.append("Constraint name: " + diagnostic.constraint_name)
+
+    if diagnostic.source_file is not None:
+        fields.append("File: " + diagnostic.source_file)
+
+    if diagnostic.source_line is not None:
+        fields.append("Line: " + diagnostic.source_line)
+
+    if diagnostic.source_function is not None:
+        fields.append("Routine: " + diagnostic.source_function)
+
+    return "\n".join(fields)
+
+
+def exception_formatter(e, verbose_errors: bool = False):
+    s = str(e)
+    if verbose_errors:
+        s += "\n" + diagnostic_output(e.diag)
+    return click.style(s, fg="red")
 
 
 def format_output(title, cur, headers, status, settings, explain_mode=False):
@@ -1724,5 +1925,28 @@ def parse_service_info(service):
     return service_conf, service_file
 
 
+def duration_in_words(duration_in_seconds: float) -> str:
+    if not duration_in_seconds:
+        return "0 seconds"
+    components = []
+    hours, remainder = divmod(duration_in_seconds, 3600)
+    if hours > 1:
+        components.append(f"{hours} hours")
+    elif hours == 1:
+        components.append("1 hour")
+    minutes, seconds = divmod(remainder, 60)
+    if minutes > 1:
+        components.append(f"{minutes} minutes")
+    elif minutes == 1:
+        components.append("1 minute")
+    if seconds >= 2:
+        components.append(f"{int(seconds)} seconds")
+    elif seconds >= 1:
+        components.append("1 second")
+    elif seconds:
+        components.append(f"{round(seconds, 3)} second")
+    return " ".join(components)
+
+
 if __name__ == "__main__":
     cli()