mycli 2.5.0__tar.gz → 2.6.1__tar.gz

{mycli-2.5.0/mycli.egg-info → mycli-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycli
-Version: 2.5.0
+Version: 2.6.1
 Summary: CLI for MySQL Database. With auto-completion and syntax highlighting.
 Author: Mycli Core Team
 License-Expression: BSD-3-Clause
@@ -39,6 +39,7 @@ Requires-Dist: pip==26.*; extra == "llm"
 Provides-Extra: dataframe
 Requires-Dist: polars~=1.42.1; extra == "dataframe"
 Requires-Dist: altair~=6.2.2; extra == "dataframe"
+Requires-Dist: vl-convert-python~=1.9.0; extra == "dataframe"
 Provides-Extra: all
 Requires-Dist: mycli[dataframe,llm]; extra == "all"
 Provides-Extra: dev
@@ -58,6 +59,7 @@ Requires-Dist: pip==26.*; extra == "dev"
 Requires-Dist: ruff~=0.15.0; extra == "dev"
 Requires-Dist: polars~=1.42.1; extra == "dev"
 Requires-Dist: altair~=6.2.2; extra == "dev"
+Requires-Dist: vl-convert-python~=1.9.0; extra == "dev"
 Dynamic: license-file
 
 # mycli
@@ -67,10 +69,11 @@ Dynamic: license-file
 A command line client for MySQL with auto-completion and syntax highlighting.
 
 Homepage: [https://mycli.net](https://mycli.net)
+
 Documentation: [https://mycli.net/docs](https://mycli.net/docs)
 
-![Completion](doc/screenshots/tables.png)
-![CompletionGif](doc/screenshots/main.gif)
+![Completion](https://raw.githubusercontent.com/dbcli/mycli/main/doc/screenshots/tables.png)
+![CompletionGif](https://raw.githubusercontent.com/dbcli/mycli/main/doc/screenshots/main.gif)
 
 Mycli is compatible with MySQL, MariaDB, Percona, TiDB, and Apache Doris.
 
@@ -133,7 +136,7 @@ Features
 * Pretty print tabular data (with colors!).
 * Support for SSL connections
 * Shell-style trailing redirects with `$>`, `$>>` and `$|` operators.
-* [Polars](https://pola.rs) dataframe [transforms](doc/transforms.md) with `.|` and Parquet saves with `.>`.
+* [Polars](https://pola.rs) dataframe [transforms and plots](doc/transforms.md) with `.|`, and Parquet saves with `.>`.
 * Support for querying LLMs with context derived from your schema using `/llm`.
 * Support for storing passwords in the system keyring.
 

{mycli-2.5.0 → mycli-2.6.1}/README.md

@@ -5,10 +5,11 @@
 A command line client for MySQL with auto-completion and syntax highlighting.
 
 Homepage: [https://mycli.net](https://mycli.net)
+
 Documentation: [https://mycli.net/docs](https://mycli.net/docs)
 
-![Completion](doc/screenshots/tables.png)
-![CompletionGif](doc/screenshots/main.gif)
+![Completion](https://raw.githubusercontent.com/dbcli/mycli/main/doc/screenshots/tables.png)
+![CompletionGif](https://raw.githubusercontent.com/dbcli/mycli/main/doc/screenshots/main.gif)
 
 Mycli is compatible with MySQL, MariaDB, Percona, TiDB, and Apache Doris.
 
@@ -71,7 +72,7 @@ Features
 * Pretty print tabular data (with colors!).
 * Support for SSL connections
 * Shell-style trailing redirects with `$>`, `$>>` and `$|` operators.
-* [Polars](https://pola.rs) dataframe [transforms](doc/transforms.md) with `.|` and Parquet saves with `.>`.
+* [Polars](https://pola.rs) dataframe [transforms and plots](doc/transforms.md) with `.|`, and Parquet saves with `.>`.
 * Support for querying LLMs with context derived from your schema using `/llm`.
 * Support for storing passwords in the system keyring.
 

{mycli-2.5.0 → mycli-2.6.1}/changelog.md

@@ -1,3 +1,40 @@
+2.6.1 (2026/07/24)
+==============
+
+Features
+---------
+* Subcommand completions for the `/dsn` command.
+* Allow file target of `$>` redirection to be quoted.
+* Display of inline plots returned from `.|` operations.
+* Don't attempt inline plots in the Windows console.
+* Save plots, like parquets, with the `.>` operator.
+* Display many native Python types returned from `.|` operations.
+
+
+Bug Fixes
+---------
+* Keep Vault username and password fields from being confused.
+* Allow `\g` to terminate `.>` expressions.
+
+
+Documentation
+---------
+* `README.md` formatting.
+
+
+Internal
+---------
+* Sync test myclirc file closer to package myclirc file.
+
+
+2.5.1 (2026/07/22)
+==============
+
+Documentation
+---------
+* Attempt to make `README.md` images display on PyPi.
+
+
 2.5.0 (2026/07/22)
 ==============
 

mycli-2.6.1/doc/transforms.md

@@ -0,0 +1,128 @@
+# Transforms, Plots, and Parquets with Polars Dataframes
+
+## Installing
+
+Install mycli with dataframe support using:
+
+```bash
+pip install --upgrade 'mycli[dataframe]'
+```
+
+or install these libraries separately:
+
+ * [`polars`](https://pypi.org/project/polars/)
+ * [`altair`](https://pypi.org/project/altair/)
+ * [`vl-convert-python`](https://pypi.org/project/vl-convert-python/)
+
+## BETA STATUS
+
+Dataframe transforms and plots are new and experimental.  The interface and
+functionality may still change.
+
+Here are some known limitations:
+
+ * transforms can't be composed with `$|` shell redirection
+ * composing multiple transform operations is not supported
+ * results from `UNION`s may be unable to be transformed
+
+And there are inherent limitations to the post-processing model: the entire
+SQL result must be transferred from the server and loaded into local memory.
+
+## Transforming
+
+In the interactive REPL, append the `.|` operator and a Python expression to a
+single SQL statement.  The Python expression receives
+
+ * `df`, a Polars `DataFrame`
+ * `pl`, the Polars module
+ * `alt`, the Altair module
+
+Spaces may be required around the `.|` operator.
+
+Transform example:
+
+```sql
+SELECT * FROM orders .| df.group_by('customer_id').len();
+```
+
+which is equivalent to this native SQL:
+
+```sql
+SELECT customer_id, COUNT(1) AS len FROM orders GROUP BY customer_id;
+```
+
+Transform expressions run with normal Python privileges, and expressions
+should not be run from untrusted sources.
+
+If the transform operation returns a Polars `DataFrame` or `Series`, or a
+Python type which can be rendered as a table, the result is rendered by mycli
+as tabular output.  `None` return values will be silently ignored, and other
+return types will result in a warning message.
+
+Transform expressions are useful for operations such as medians which
+cannot be done (or are awkward) in SQL.  Example:
+
+```sql
+SELECT * FROM orders .| df.describe();
+```
+
+## Plotting
+
+If the dataframe transform operation returns an Altair plot, the result can
+be rendered as an inline PNG in many terminals.
+
+Example:
+
+```sql
+SELECT * FROM orders .| df['total'].plot.hist();
+```
+
+<img src="https://raw.githubusercontent.com/dbcli/mycli/main/doc/screenshots/total_histogram.png" height=400>
+
+Image size, display protocol, and other properties can be configured in
+the `[dataframe]` section of `~/.myclirc`.
+
+## Saving
+
+A query result, transformed `DataFrame`, or transformed `Series` can be
+written directly to a Parquet file with the `.>` operator. An Altair plot can
+also be written to a file with the same operator.
+
+Save example:
+
+```sql
+SELECT * FROM orders .> orders.parquet;
+```
+
+The `.>` operator must be last, requires a `.parquet`, `.png`, `.pdf`, `.svg`,
+or `.html` file extension on the destination, and overwrites any existing file.
+
+Spaces may be required around the operator.  Destination paths containing
+whitespace must be quoted.  A successful write reports its destination and row
+count if appropriate.
+
+When saving a plot, the format is deduced from the file extension.
+
+When `post_redirect_command` is set in `~/.myclirc`, the given command runs
+after a successful file save.
+
+`.>` cannot be combined with the `\x` or `\G` special display terminators.
+
+## Combining
+
+Parquet saves may be combined with dataframe transforms.  Again, the save
+operator `.>` must be the last operator.
+
+Combined transform and save examples:
+
+```sql
+SELECT * FROM orders .| df.group_by('customer_id').len() .> customer_counts.parquet;
+```
+
+```sql
+SELECT * FROM orders .| df['order_id'] .> order_ids.parquet;
+```
+
+```sql
+SELECT * FROM orders .| df['total'].plot.hist() .> total_histogram.png;
+```

{mycli-2.5.0 → mycli-2.6.1}/mycli/TIPS

@@ -296,8 +296,8 @@ customize password sources/precedence with "password_sources" in ~/.myclirc!
 
 redirect query output to a shell command with "$| <command>"!
 
-redirect query output to a file with "$> <filename>"!
+redirect query output to a CSV file with "$> <filename>"!
 
-append query output to a file with "$>> <filename>"!
+append query output to a CSV file with "$>> <filename>"!
 
 run a command after shell redirects with "post_redirect_command" in ~/.myclirc!

{mycli-2.5.0 → mycli-2.6.1}/mycli/app_state.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any
 from configobj import ConfigObj
 
 from mycli.config import strip_matching_quotes
+from mycli.types import ImageProtocol
 
 if TYPE_CHECKING:
     from mycli.client import MyCli
@@ -46,6 +47,16 @@ def normalize_ssl_mode(
     return ssl_mode, error_notice
 
 
+def normalize_image_protocol(image_protocol: str | None) -> tuple[ImageProtocol, str | None]:
+    if image_protocol == 'iterm2':
+        return 'iterm2', None
+    if image_protocol == 'kitty':
+        return 'kitty', None
+    if image_protocol in ('none', '', None):
+        return 'none', None
+    return 'none', f'Invalid config option provided for image_protocol ({image_protocol}); disabling.'
+
+
 def configure_prompt_state(
     mycli: MyCli,
     config: ConfigObj,

{mycli-2.5.0 → mycli-2.6.1}/mycli/cli_runner.py

@@ -384,13 +384,13 @@ def run_from_cli_args(cli_args: 'CliArgs', client_factory: ClientFactory) -> Non
         vault_config = mycli.config.get('vault_beta', {})
         vault_address = cli_args.vault_address or os.environ.get('VAULT_ADDR') or vault_config.get('address') or None
         vault_mount = cli_args.vault_mount or vault_config.get('default_mount') or None
-        vault_field = cli_args.vault_password_field or vault_config.get('default_password_field') or DEFAULT_VAULT_PASSWORD_FIELD
+        vault_password_field = cli_args.vault_password_field or vault_config.get('default_password_field') or DEFAULT_VAULT_PASSWORD_FIELD
         vault_executable = vault_config.get('vault_executable') or DEFAULT_VAULT_EXECUTABLE
 
         def load_vault_password() -> str | None:
             try:
                 return get_field_from_vault(
-                    vault_field,
+                    vault_password_field,
                     vault_secret,
                     executable=vault_executable,
                     mount=vault_mount,
@@ -406,11 +406,11 @@ def run_from_cli_args(cli_args: 'CliArgs', client_factory: ClientFactory) -> Non
         vault_config = mycli.config.get('vault_beta', {})
         vault_address = cli_args.vault_address or os.environ.get('VAULT_ADDR') or vault_config.get('address') or None
         vault_mount = cli_args.vault_mount or vault_config.get('default_mount') or None
-        vault_field = cli_args.vault_username_field or vault_config.get('default_username_field') or DEFAULT_VAULT_USERNAME_FIELD
+        vault_username_field = cli_args.vault_username_field or vault_config.get('default_username_field') or DEFAULT_VAULT_USERNAME_FIELD
         vault_executable = vault_config.get('vault_executable') or DEFAULT_VAULT_EXECUTABLE
         try:
             vault_username = get_field_from_vault(
-                vault_field,
+                vault_username_field,
                 cli_args.vault_secret,
                 executable=vault_executable,
                 mount=vault_mount,

{mycli-2.5.0 → mycli-2.6.1}/mycli/client.py

@@ -17,6 +17,7 @@ from mycli.app_state import (
     configure_prompt_state,
     destructive_keywords_from_config,
     llm_prompt_truncation,
+    normalize_image_protocol,
     normalize_ssl_mode,
 )
 from mycli.client_commands import ClientCommandsMixin
@@ -145,6 +146,12 @@ class MyCli(AppStateMixin, OutputMixin, ClientCommandsMixin, ClientConnectionMix
         self.null_string = c['main'].get('null_string')
         self.numeric_alignment = c['main'].get('numeric_alignment', 'right') or 'right'
         self.binary_display = c['main'].get('binary_display')
+        self.image_protocol, image_protocol_error = normalize_image_protocol(c['dataframe'].get('image_protocol'))
+        if image_protocol_error:
+            self.echo(image_protocol_error, err=True, fg='red')
+        self.plot_scale_factor = c['dataframe'].as_float('plot_scale_factor')
+        self.plot_ppi = c['dataframe'].as_int('plot_ppi')
+        self.plot_theme = c['dataframe'].get('plot_theme', 'carbong90') or 'carbong90'
         self.llm_prompt_field_truncate, self.llm_prompt_section_truncate = llm_prompt_truncation(c)
 
         self.ssl_mode, ssl_mode_error = normalize_ssl_mode(c, self.config_without_package_defaults)

mycli-2.6.1/mycli/compat.py

@@ -0,0 +1,27 @@
+"""Platform and Python version compatibility support."""
+
+from importlib import import_module
+import sys
+
+WIN: bool = sys.platform in ("win32", "cygwin")
+
+
+def _is_win32() -> bool:
+    return sys.platform == 'win32'
+
+
+def is_windows_console(output: object | None) -> bool:
+    """Return whether output uses a native Windows console backend."""
+    if not _is_win32() or output is None:
+        return False
+
+    output_types = tuple(
+        getattr(import_module(module_name), class_name)
+        for module_name, class_name in (
+            ('prompt_toolkit.output.conemu', 'ConEmuOutput'),
+            ('prompt_toolkit.output.win32', 'Win32Output'),
+            ('prompt_toolkit.output.windows10', 'Windows10_Output'),
+        )
+    )
+
+    return isinstance(output, output_types)

{mycli-2.5.0 → mycli-2.6.1}/mycli/main_modes/repl.py

@@ -750,20 +750,35 @@ def _one_iteration(
         mycli.explorer_formatter.query = text
         if polars_transform is not None:
             assert polars_pipeline is not None
-            if polars_pipeline.parquet_path is None:
-                polars_result = run_polars_transform(polars_transform, results)
+            if polars_pipeline.output_path is None:
+                polars_result = run_polars_transform(
+                    polars_transform,
+                    results,
+                    image_protocol=mycli.image_protocol,
+                    plot_scale_factor=mycli.plot_scale_factor,
+                    plot_ppi=mycli.plot_ppi,
+                    plot_theme=mycli.plot_theme,
+                )
             else:
-                polars_result = run_polars_transform(polars_transform, results, polars_pipeline.parquet_path)
-            if polars_pipeline.parquet_path is None:
+                polars_result = run_polars_transform(
+                    polars_transform,
+                    results,
+                    polars_pipeline.output_path,
+                    image_protocol=mycli.image_protocol,
+                    plot_scale_factor=mycli.plot_scale_factor,
+                    plot_ppi=mycli.plot_ppi,
+                    plot_theme=mycli.plot_theme,
+                )
+            if polars_pipeline.output_path is None:
                 if polars_pipeline.output_mode == 'explorer':
                     special.set_explorer_output(True)
                 elif polars_pipeline.output_mode == 'expanded':
                     special.set_expanded_output(True)
             _output_results(mycli, state, iter([polars_result]), start)
-            if polars_pipeline.parquet_path is not None:
+            if polars_pipeline.output_path is not None:
                 special.run_post_redirect_hook(
                     mycli.post_redirect_command,
-                    polars_pipeline.parquet_path,
+                    polars_pipeline.output_path,
                 )
         else:
             _output_results(mycli, state, results, start)

{mycli-2.5.0 → mycli-2.6.1}/mycli/myclirc

@@ -265,6 +265,27 @@ format = mysql_unicode
 # Whether to remove the last line from the formatted output.
 trim_footer = False
 
+[dataframe]
+
+# How to display inline image results in a terminal emulator. Possible values:
+# * kitty
+# * iterm2
+# empty to disable
+image_protocol = kitty
+
+# PNG plot resolution in pixels per inch. Must be a positive integer.
+# The apparent size is a combination of plot_ppi and plot_scale_factor.
+plot_ppi = 200
+
+# PNG plot resolution multiplier. Must be a positive number.
+# The apparent size is a combination of plot_ppi and plot_scale_factor.
+plot_scale_factor = 1.0
+
+# Altair theme for rendering plots. Examples: carbong90, dark, default.
+# Available themes depend on the installed libraries.  See
+# https://github.com/vega/vega-themes/#included-themes
+plot_theme = carbong90
+
 [search]
 
 # Whether to apply syntax highlighting to the preview window in fuzzy history

{mycli-2.5.0 → mycli-2.6.1}/mycli/output.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import base64
 from datetime import datetime
 from decimal import Decimal
 from io import TextIOWrapper
@@ -28,7 +29,7 @@ from prompt_toolkit.styles.style import _MergedStyle
 from pygments.style import Style as PygmentsStyle
 from pymysql.cursors import Cursor
 
-from mycli.compat import WIN
+from mycli.compat import WIN, is_windows_console
 from mycli.constants import DEFAULT_HEIGHT, DEFAULT_WIDTH
 import mycli.main_modes.repl as repl_mode
 from mycli.packages import special
@@ -115,6 +116,14 @@ class OutputMixin(MyCliState):
         is_warnings_style: bool = False,
     ) -> None:
         """Output text to stdout or a pager command."""
+        prompt_output = self.prompt_session.output if self.prompt_session is not None else None
+        if result.image is not None and not is_windows_console(prompt_output):
+            if result.image_protocol == 'iterm2':
+                click.secho('')
+                self.output_iterm2_image(result.image)
+            elif result.image_protocol == 'kitty':
+                click.secho('')
+                self.output_kitty_image(result.image)
         if output:
             if self.prompt_session is not None:
                 size = self.prompt_session.output.get_size()
@@ -186,6 +195,22 @@ class OutputMixin(MyCliState):
             styled_status = to_formatted_text(status, style=add_style)
             prompt_toolkit.print_formatted_text(styled_status, style=self.ptoolkit_style)
 
+    def output_iterm2_image(self, image: bytes) -> None:
+        """Emit a PNG using the iTerm2 inline image protocol."""
+        filename = base64.b64encode(b'chart.png').decode('ascii')
+        contents = base64.b64encode(image).decode('ascii')
+        click.echo(f'\x1b]1337;File=name={filename};size={len(image)};width=auto;height=auto;preserveAspectRatio=1;inline=1:{contents}\x07')
+
+    def output_kitty_image(self, image: bytes) -> None:
+        """Emit a PNG using Kitty's direct graphics protocol."""
+        contents = base64.b64encode(image).decode('ascii')
+        chunks = [contents[index : index + 4096] for index in range(0, len(contents), 4096)] or ['']
+        for index, chunk in enumerate(chunks):
+            action = 'a=T,f=100,' if index == 0 else ''
+            more = 1 if index < len(chunks) - 1 else 0
+            click.echo(f'\x1b_G{action}m={more};{chunk}\x1b\\', nl=False)
+        click.echo()
+
     def configure_pager(self) -> None:
         if not os.environ.get("LESS"):
             os.environ["LESS"] = "-RXF"

{mycli-2.5.0 → mycli-2.6.1}/mycli/packages/completion_engine.py

@@ -6,6 +6,7 @@ from typing import Any, Callable, Literal
 import sqlparse
 from sqlparse.sql import Comparison, Identifier, Token, Where
 
+from mycli.packages.special.dsn_aliases import DSN_SUBCOMMANDS
 from mycli.packages.special.main import COMMANDS as SPECIAL_COMMANDS
 from mycli.packages.special.main import parse_special_command
 from mycli.packages.sql_utils import extract_tables, find_prev_keyword, last_word
@@ -816,6 +817,17 @@ def suggest_special(text: str) -> list[dict[str, Any]]:
     if cmd in ["\\llm", "/llm", "\\ai", "/ai"]:
         return [{"type": "llm"}]
 
+    if cmd.lower() in (r'\dsn', '/dsn'):
+        dsn_arguments = _arg.split(maxsplit=1)
+        completing_delete_target = (len(dsn_arguments) == 1 and text[-1].isspace()) or (len(dsn_arguments) == 2 and not text[-1].isspace())
+        if dsn_arguments and dsn_arguments[0].lower() == 'delete' and completing_delete_target:
+            return [{'type': 'dsn_alias'}]
+        if dsn_arguments and dsn_arguments[0].lower() == 'delete' and len(dsn_arguments) == 2:
+            return []
+        if dsn_arguments and dsn_arguments[0].lower() in DSN_SUBCOMMANDS - {'delete'}:
+            return []
+        return [{'type': 'special_subcommand', 'subcommands': list(DSN_SUBCOMMANDS)}]
+
     return [{"type": "keyword"}, {"type": "special"}]
 
 

{mycli-2.5.0 → mycli-2.6.1}/mycli/packages/hybrid_redirection.py

@@ -1,5 +1,6 @@
 import functools
 import logging
+import shlex
 
 import sqlglot
 
@@ -113,9 +114,6 @@ def invalid_shell_part(
     file_part: str | None,
     command_part: str | None,
 ) -> bool:
-    if file_part and ' ' in file_part:
-        return True
-
     if file_part and '>' in file_part:
         return True
 
@@ -125,6 +123,19 @@ def invalid_shell_part(
     return False
 
 
+def parse_redirect_filename(file_part: str | None) -> str | None:
+    """Return one unquoted redirect filename, or None for an invalid operand."""
+    if file_part is None or not file_part:
+        return None
+    if file_part[0] not in ('\'', '"'):
+        return file_part if not any(character.isspace() for character in file_part) else None
+    try:
+        parts = shlex.split(file_part)
+    except ValueError:
+        return None
+    return parts[0] if len(parts) == 1 else None
+
+
 # todo there are still corner cases combining custom delimiters, caching, and redirection
 @functools.lru_cache(maxsize=1)
 def get_redirect_components(command: str) -> tuple[str | None, str | None, str | None, str | None]:
@@ -174,7 +185,9 @@ def get_redirect_components(command: str) -> tuple[str | None, str | None, str |
     )
 
     if file_part_tokens:
-        file_part = assemble_tokens(file_part_tokens)
+        file_part = parse_redirect_filename(assemble_tokens(file_part_tokens))
+        if file_part is None:
+            return None, None, None, None
     else:
         file_part = None