kash-shell 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

kash/config/logger.py

@@ -2,7 +2,6 @@ import contextvars
 import logging
 import os
 import re
-import threading
 from collections.abc import Generator
 from contextlib import contextmanager
 from dataclasses import dataclass
@@ -17,7 +16,7 @@ from rich._null_file import NULL_FILE
 from rich.console import Console
 from rich.logging import RichHandler
 from rich.theme import Theme
-from strif import atomic_output_file, new_timestamped_uid
+from strif import AtomicVar, atomic_output_file, new_timestamped_uid
 from typing_extensions import override
 
 import kash.config.suppress_warnings  # noqa: F401
@@ -38,55 +37,41 @@ from kash.utils.common.stack_traces import current_stack_traces
 from kash.utils.common.task_stack import task_stack_prefix_str
 
 
-@dataclass(frozen=True)
+@dataclass
 class LogSettings:
     log_console_level: LogLevel
     log_file_level: LogLevel
-    # Always the same global log directory.
+
     global_log_dir: Path
+    """Global directory for log files."""
 
     # These directories can change based on the current workspace:
     log_dir: Path
-    log_objects_dir: Path
-    log_file_path: Path
-
-
-_log_dir = get_system_logs_dir()
-"""
-Parent of the "logs" directory. Initially the global kash workspace.
-"""
-
-
-LOG_NAME_GLOBAL = "global"
+    """Parent of the "logs" directory. Initially the global kash workspace."""
 
-_log_name = LOG_NAME_GLOBAL
-"""
-Name of the log file. By default the workspace name or "global" if
-for the global workspace.
-"""
+    log_name: str
+    """Name of the log file. Typically the workspace name or "workspace" if for the global workspace."""
 
-_log_lock = threading.RLock()
+    log_objects_dir: Path
+    log_file_path: Path
 
 
-def make_valid_log_name(name: str) -> str:
-    name = str(name).strip().rstrip("/").removesuffix(".log")
-    name = re.sub(r"[^\w-]", "_", name)
-    return name
+LOG_NAME_GLOBAL = "workspace"
 
 
 def _read_log_settings() -> LogSettings:
-    global _log_dir, _log_name
     return LogSettings(
         log_console_level=global_settings().console_log_level,
         log_file_level=global_settings().file_log_level,
         global_log_dir=get_system_logs_dir(),
-        log_dir=_log_dir,
-        log_objects_dir=_log_dir / "objects" / _log_name,
-        log_file_path=_log_dir / f"{_log_name}.log",
+        log_dir=get_system_logs_dir(),
+        log_name=LOG_NAME_GLOBAL,
+        log_objects_dir=get_system_logs_dir() / "objects" / LOG_NAME_GLOBAL,
+        log_file_path=get_system_logs_dir() / f"{LOG_NAME_GLOBAL}.log",
     )
 
 
-_log_settings: LogSettings = _read_log_settings()
+_log_settings: AtomicVar[LogSettings] = AtomicVar(_read_log_settings())
 
 _setup_done = False
 
@@ -95,19 +80,13 @@ def get_log_settings() -> LogSettings:
     """
     Currently active log settings.
     """
-    return _log_settings
+    return _log_settings.copy()
 
 
-def reset_log_root(log_root: Path | None = None, log_name: str | None = None):
-    """
-    Reset the logging root or log name, if it has changed. None means no change
-    and global default values.
-    """
-    global _log_lock, _log_base, _log_name
-    with _log_lock:
-        _log_base = log_root or get_system_logs_dir()
-        _log_name = make_valid_log_name(log_name or LOG_NAME_GLOBAL)
-        reload_rich_logging_setup()
+def make_valid_log_name(name: str) -> str:
+    name = str(name).strip().rstrip("/").removesuffix(".log")
+    name = re.sub(r"[^\w-]", "_", name)
+    return name
 
 
 console_context_var: contextvars.ContextVar[Console | None] = contextvars.ContextVar(
@@ -169,6 +148,30 @@ _file_handler: logging.FileHandler
 _console_handler: logging.Handler
 
 
+def reset_rich_logging(
+    log_root: Path | None = None,
+    log_name: str | None = None,
+    log_path: Path | None = None,
+):
+    """
+    Set or reset the logging root or log name, if it has changed. None means no change
+    and global default values. `log_name` is the name of the log, excluding
+    the `.log` extension. If `log_path` is provided, it will be used to infer
+    the log root and name.
+    """
+    if log_path:
+        if not log_path.parent.exists():
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+        log_root = log_path.parent
+        log_name = log_path.name
+
+    global _log_settings
+    with _log_settings.updates() as settings:
+        settings.log_dir = log_root or get_system_logs_dir()
+        settings.log_name = make_valid_log_name(log_name or LOG_NAME_GLOBAL)
+        reload_rich_logging_setup()
+
+
 def reload_rich_logging_setup():
     """
     Set up or reset logging setup. This is for rich/formatted console logging and
@@ -176,12 +179,12 @@ def reload_rich_logging_setup():
     Call at initial run and again if log directory changes. Replaces all previous
     loggers and handlers. Can be called to reset with different settings.
     """
-    global _log_lock, _log_settings, _setup_done
-    with _log_lock:
+    global _setup_done, _log_settings
+    with _log_settings.lock:
         new_log_settings = _read_log_settings()
-        if not _setup_done or new_log_settings != _log_settings:
+        if not _setup_done or new_log_settings != _log_settings.value:
             _do_logging_setup(new_log_settings)
-            _log_settings = new_log_settings
+            _log_settings.set(new_log_settings)
             _setup_done = True
 
             # get_console().print(
@@ -190,6 +193,15 @@ def reload_rich_logging_setup():
             # )
 
 
+@cache
+def _init_rich_logging():
+    rich.reconfigure(theme=get_theme(), highlighter=get_highlighter())
+
+    logging.setLoggerClass(CustomLogger)
+
+    reload_rich_logging_setup()
+
+
 def _do_logging_setup(log_settings: LogSettings):
     from kash.config.suppress_warnings import demote_warnings, filter_warnings
 
@@ -319,7 +331,7 @@ class CustomLogger(logging.Logger):
         filename = (
             f"{prefix}{slugify_snake(description)}.{new_timestamped_uid()}.{file_ext.lstrip('.')}"
         )
-        path = _log_settings.log_objects_dir / filename
+        path = _log_settings.copy().log_objects_dir / filename
         with atomic_output_file(path, make_parents=True) as tmp_filename:
             if isinstance(obj, bytes):
                 with open(tmp_filename, "wb") as f:
@@ -346,7 +358,7 @@ def get_logger(name: str) -> CustomLogger:
     Get a logger that's compatible with system logging but has our additional custom
     methods.
     """
-    init_rich_logging()
+    _init_rich_logging()
     logger = logging.getLogger(name)
     # print("Logger is", logger)
     return cast(CustomLogger, logger)
@@ -354,12 +366,3 @@ def get_logger(name: str) -> CustomLogger:
 
 def get_log_file_stream():
     return _file_handler.stream
-
-
-@cache
-def init_rich_logging():
-    rich.reconfigure(theme=get_theme(), highlighter=get_highlighter())
-
-    logging.setLoggerClass(CustomLogger)
-
-    reload_rich_logging_setup()

kash/config/logger_basic.py

@@ -30,7 +30,7 @@ def basic_stderr_handler(level: LogLevel) -> logging.StreamHandler:
     return handler
 
 
-def basic_logging_setup(file_log_path: Path | None, level: LogLevel):
+def basic_logging_setup(log_path: Path | None, level: LogLevel):
     """
     Set up basic logging to a file and to stderr.
     """
@@ -38,8 +38,8 @@ def basic_logging_setup(file_log_path: Path | None, level: LogLevel):
     for h in root_logger.handlers[:]:
         root_logger.removeHandler(h)
 
-    if file_log_path:
-        file_handler: FileHandler = basic_file_handler(file_log_path, level)
+    if log_path:
+        file_handler: FileHandler = basic_file_handler(log_path, level)
         root_logger.addHandler(file_handler)
 
     stderr_handler = basic_stderr_handler(level)

kash/config/settings.py

@@ -5,15 +5,16 @@ from logging import DEBUG, ERROR, INFO, WARNING
 from pathlib import Path
 
 from pydantic.dataclasses import dataclass
+from strif import AtomicVar
 
 from kash.config.env_settings import KashEnv
-from kash.utils.common.atomic_var import AtomicVar
 
 APP_NAME = "kash"
 
 DOT_DIR = ".kash"
 
-GLOBAL_WS_NAME = "global"
+GLOBAL_WS_NAME = "workspace"
+"""Name of the global workspace."""
 
 RECOMMENDED_API_KEYS = [
     "OPENAI_API_KEY",
@@ -23,51 +24,28 @@ RECOMMENDED_API_KEYS = [
 ]
 
 
-def get_ws_root_dir() -> Path:
-    """Default root directory for kash workspaces."""
-    return KashEnv.KASH_WS_ROOT.read_path(Path("~/Kash"))
-
-
-def get_global_ws_dir() -> Path:
-    """Default global workspace directory."""
-    kash_ws_dir = KashEnv.KASH_GLOBAL_WS.read_path(None)
-    if kash_ws_dir:
-        return kash_ws_dir
-    else:
-        return get_ws_root_dir() / GLOBAL_WS_NAME
-
-
-def get_system_config_dir() -> Path:
-    return Path("~/.config/kash").expanduser().resolve()
-
-
-def get_rcfile_path() -> Path:
-    return get_system_config_dir() / "kashrc"
-
-
-def get_system_logs_dir() -> Path:
-    """Default global and system logs directory (for server logs, etc)."""
-    return KashEnv.KASH_SYSTEM_LOGS_DIR.read_path(get_ws_root_dir() / "logs")
-
-
-def get_system_cache_dir() -> Path:
-    """Default global and system cache directory (for global media, content, etc)."""
-    return KashEnv.KASH_SYSTEM_CACHE_DIR.read_path(get_ws_root_dir() / "cache")
-
-
-def get_system_env_path() -> Path:
-    return get_system_config_dir() / "env.local"
-
-
-def get_mcp_ws_dir() -> Path | None:
+def get_all_common_api_env_vars() -> list[str]:
     """
-    Get the directory for the MCP workspace, if set.
+    Get all the common environment variables that are recommended to be set.
     """
-    mcp_dir = KashEnv.KASH_MCP_WS.read_str()
-    if mcp_dir:
-        return Path(mcp_dir).expanduser().resolve()
-    else:
-        return None
+    from clideps.env_vars.env_names import get_all_common_env_names
+
+    return list(set(get_all_common_env_names() + RECOMMENDED_API_KEYS))
+
+
+RECOMMENDED_PKGS = [
+    "less",
+    "eza",
+    "ripgrep",
+    "bat",
+    "zoxide",
+    "dust",
+    "duf",
+    "pygmentize",
+    "hexyl",
+    "ffmpeg",
+    "imagemagick",
+]
 
 
 MEDIA_CACHE_NAME = "media"
@@ -86,11 +64,6 @@ LOCAL_SERVER_PORTS_MAX = 30
 LOCAL_SERVER_LOG_NAME = "local_server"
 
 
-@cache
-def local_server_log_path() -> Path:
-    return resolve_and_create_dirs(get_system_logs_dir() / f"{LOCAL_SERVER_LOG_NAME}.log")
-
-
 class LogLevel(Enum):
     debug = DEBUG
     info = INFO
@@ -146,11 +119,15 @@ def find_in_cwd_or_parents(filename: Path | str) -> Path | None:
     return None
 
 
+def _get_rcfile_path() -> Path:
+    return _get_system_config_dir() / "kashrc"
+
+
 def find_rcfiles() -> list[Path]:
     """
     Find active rcfiles. Currently only supports one.
     """
-    rcfile_path = get_rcfile_path()
+    rcfile_path = _get_rcfile_path()
     if rcfile_path.exists():
         return [rcfile_path]
     else:
@@ -159,9 +136,30 @@ def find_rcfiles() -> list[Path]:
 
 @dataclass
 class Settings:
+    ws_root_dir: Path
+    """A default root directory for kash workspaces (typically `~/Kash`)."""
+
+    global_ws_dir: Path
+    """The directory for the default global workspace."""
+
+    system_config_dir: Path
+    """The directory for system-wide configuration files."""
+
     media_cache_dir: Path
     """The workspace media cache directory, for caching audio, video, and transcripts."""
 
+    system_logs_dir: Path
+    """Default global and system logs directory (for server logs, etc)."""
+
+    system_cache_dir: Path
+    """Default global and system cache directory (for global media, content, etc)."""
+
+    mcp_ws_dir: Path | None
+    """The directory for the MCP workspace, if set."""
+
+    local_server_log_path: Path
+    """The path to the local server log."""
+
     content_cache_dir: Path
     """The workspace content cache directory, for caching web or local files."""
     # TODO: Separate workspace cached content (e.g. thumbnails) vs global files
@@ -198,12 +196,60 @@ class Settings:
     """If true, use Nerd Icons in file listings. Requires a compatible font."""
 
 
-# Initial default settings.
-_settings = AtomicVar(
-    Settings(
+ws_root_dir = Path("~/Kash").expanduser()
+
+
+def _get_ws_root_dir() -> Path:
+    """Default root directory for kash workspaces."""
+    return KashEnv.KASH_WS_ROOT.read_path(default=ws_root_dir)
+
+
+def _get_global_ws_dir() -> Path:
+    kash_ws_dir = KashEnv.KASH_GLOBAL_WS.read_path()
+    if kash_ws_dir:
+        return kash_ws_dir
+    else:
+        return _get_ws_root_dir() / GLOBAL_WS_NAME
+
+
+def get_system_logs_dir() -> Path:
+    return KashEnv.KASH_SYSTEM_LOGS_DIR.read_path(default=_get_ws_root_dir() / "logs")
+
+
+def _get_system_config_dir() -> Path:
+    return Path("~/.config/kash").expanduser().resolve()
+
+
+def _get_system_cache_dir() -> Path:
+    return KashEnv.KASH_SYSTEM_CACHE_DIR.read_path(default=_get_ws_root_dir() / "cache")
+
+
+def _get_mcp_ws_dir() -> Path | None:
+    mcp_dir = KashEnv.KASH_MCP_WS.read_str()
+    if mcp_dir:
+        return Path(mcp_dir).expanduser().resolve()
+    else:
+        return None
+
+
+@cache
+def _get_local_server_log_path() -> Path:
+    return resolve_and_create_dirs(get_system_logs_dir() / f"{LOCAL_SERVER_LOG_NAME}.log")
+
+
+def _read_settings():
+    return Settings(
+        # Essential system settings for logs, workspaces, and configs:
+        ws_root_dir=_get_ws_root_dir(),
+        global_ws_dir=_get_global_ws_dir(),
+        system_config_dir=_get_system_config_dir(),
+        system_logs_dir=get_system_logs_dir(),
+        system_cache_dir=_get_system_cache_dir(),
+        mcp_ws_dir=_get_mcp_ws_dir(),
+        local_server_log_path=_get_local_server_log_path(),
         # These default to the global but can be overridden by workspace settings.
-        media_cache_dir=get_system_cache_dir() / MEDIA_CACHE_NAME,
-        content_cache_dir=get_system_cache_dir() / CONTENT_CACHE_NAME,
+        media_cache_dir=_get_system_cache_dir() / MEDIA_CACHE_NAME,
+        content_cache_dir=_get_system_cache_dir() / CONTENT_CACHE_NAME,
         debug_assistant=True,
         default_editor="nano",
         file_log_level=LogLevel.info,
@@ -215,7 +261,20 @@ _settings = AtomicVar(
         use_kerm_codes=False,
         use_nerd_icons=True,
     )
-)
+
+
+# Initial default settings.
+_settings = AtomicVar(_read_settings())
+
+
+def configure_ws_and_settings(root_dir: Path):
+    """
+    Reset and reload all settings, deriving all paths from the new workspace
+    root. Good if embedding kash in another app.
+    """
+    global ws_root_dir
+    ws_root_dir = root_dir
+    _settings.set(_read_settings())
 
 
 def atomic_global_settings() -> AtomicVar[Settings]:

kash/config/setup.py

@@ -3,34 +3,50 @@ from functools import cache
 from pathlib import Path
 from typing import Any
 
+from clideps.env_vars.dotenv_utils import load_dotenv_paths
+
+from kash.config.logger import reset_rich_logging
 from kash.config.logger_basic import basic_logging_setup
-from kash.config.settings import LogLevel, get_system_config_dir
+from kash.config.settings import LogLevel, configure_ws_and_settings, global_settings
 
 
 @cache
-def setup(rich_logging: bool, file_log_path: Path | None = None, level: LogLevel = LogLevel.info):
+def kash_setup(
+    *,
+    rich_logging: bool,
+    kash_ws_root: Path | None = None,
+    log_path: Path | None = None,
+    level: LogLevel = LogLevel.info,
+):
     """
     One-time top-level setup of essential logging, keys, directories, and configs.
     Idempotent.
 
-    If rich_logging is True, then rich logging with warnings only for console use.
-    If rich_logging is False, then use basic logging to a file and stderr.
+    Can call this if embedding kash in another app.
+    Can be used to set the global default workspace and logs directory
+    and/or the default log file.
+    If `rich_logging` is True, then rich logging with warnings only for console use.
+    If `rich_logging` is False, then use basic logging to a file and stderr.
     """
-    from kash.config.logger import reload_rich_logging_setup
-    from kash.shell.clideps.dotenv_utils import load_dotenv_paths
     from kash.utils.common.stack_traces import add_stacktrace_handler
 
+    add_stacktrace_handler()
+
+    # Settings may depend on environment variables, so load them first.
+    load_dotenv_paths(True, True, global_settings().system_config_dir)
+
+    # Then configure the workspace and settings before finalizing logging.
+    if kash_ws_root:
+        configure_ws_and_settings(kash_ws_root)
+
+    # Now set up logging, as it might depend on workspace root.
     if rich_logging:
-        reload_rich_logging_setup()
+        reset_rich_logging(log_path=log_path)
     else:
-        basic_logging_setup(file_log_path=file_log_path, level=level)
+        basic_logging_setup(log_path=log_path, level=level)
 
     _lib_setup()
 
-    add_stacktrace_handler()
-
-    load_dotenv_paths(True, True, get_system_config_dir())
-
 
 def _lib_setup():
     from frontmatter_format.yaml_util import add_default_yaml_customizer

kash/config/text_styles.py

@@ -46,7 +46,9 @@ SPINNER = "dots12"
 
 BAT_THEME = "Coldark-Dark"
 
-BAT_STYLE = "header-filename,header-filesize,grid,changes"
+BAT_STYLE = "header-filename,header-filesize,grid,numbers,changes"
+
+BAT_STYLE_PLAIN = "plain"
 
 
 ## Colors
@@ -296,18 +298,6 @@ EMOJI_MSG_INDENT = "⋮"
 
 EMOJI_BREADCRUMB_SEP = "›"
 
-EMOJI_TRUE = "✔︎"
-
-EMOJI_FALSE = "✘"
-
-
-def success_emoji(value: bool, success_only: bool = False) -> str:
-    return EMOJI_TRUE if value else " " if success_only else EMOJI_FALSE
-
-
-def format_success_emoji(value: bool, success_only: bool = False) -> Text:
-    return Text(success_emoji(value, success_only), style=COLOR_SUCCESS if value else COLOR_FAILURE)
-
 
 ## Special headings
 

kash/docs/load_api_docs.py

@@ -1,7 +1,8 @@
+from strif import StringTemplate
+
 from kash.config.logger import get_logger
 from kash.docs.load_help_topics import load_help_src
 from kash.docs.load_source_code import load_source_code
-from kash.utils.common.string_template import StringTemplate
 
 log = get_logger(__name__)
 

kash/docs/markdown/topics/a3_getting_started.md

@@ -243,8 +243,9 @@ A few of the most important commands for managing files and work are these:
   browser to view it.
 
 - `workspace` shows or selects or creates a new workspace.
-  Initially you work in the `global` workspace but for more real work you'll want to
-  create a workspace, which is a directory to hold the files you are working with.
+  Initially you work in the default global workspace (typically at `~/Kash/workspace`)
+  but for more real work you'll want to create a workspace, which is a directory to hold
+  the files you are working with.
 
 - `select` shows or sets selections, which are the set of files the next command will
   run on, within the current workspace.

kash/{concepts → embeddings}/text_similarity.py

@@ -5,9 +5,9 @@ from funlog import log_calls
 from litellm import embedding
 from litellm.types.utils import EmbeddingResponse
 
-from kash.concepts.cosine import ArrayLike, cosine
-from kash.concepts.embeddings import Embeddings
 from kash.config.logger import get_logger
+from kash.embeddings.cosine import ArrayLike, cosine
+from kash.embeddings.embeddings import Embeddings
 from kash.llm_utils.llms import DEFAULT_EMBEDDING_MODEL, EmbeddingModel
 from kash.utils.errors import ApiResultError
 

kash/exec/__init__.py

@@ -1,9 +1,7 @@
-# flake8: noqa: F401
-
 from kash.exec.action_decorators import kash_action, kash_action_class
 from kash.exec.action_exec import SkipItem, prepare_action_input, run_action_with_shell_context
-from kash.exec.action_registry import import_action_subdirs
 from kash.exec.command_registry import kash_command
+from kash.exec.importing import import_and_register
 from kash.exec.llm_transforms import llm_transform_item, llm_transform_str
 from kash.exec.precondition_registry import kash_precondition
 from kash.exec.resolve_args import (
@@ -14,3 +12,22 @@ from kash.exec.resolve_args import (
     resolve_locator_arg,
     resolve_path_arg,
 )
+
+__all__ = [
+    "kash_action",
+    "kash_action_class",
+    "SkipItem",
+    "prepare_action_input",
+    "run_action_with_shell_context",
+    "kash_command",
+    "import_and_register",
+    "llm_transform_item",
+    "llm_transform_str",
+    "kash_precondition",
+    "assemble_path_args",
+    "assemble_store_path_args",
+    "import_locator_args",
+    "resolvable_paths",
+    "resolve_locator_arg",
+    "resolve_path_arg",
+]