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

kash/text_handling/markdown_utils.py

@@ -1,5 +1,6 @@
 import re
-from typing import Any
+from textwrap import dedent
+from typing import Any, TypeAlias
 
 import marko
 import regex
@@ -11,6 +12,8 @@ from kash.utils.common.url import Url
 
 log = get_logger(__name__)
 
+HTag: TypeAlias = str
+
 # Characters that commonly need escaping in Markdown inline text.
 MARKDOWN_ESCAPE_CHARS = r"([\\`*_{}\[\]()#+.!-])"
 MARKDOWN_ESCAPE_RE = re.compile(MARKDOWN_ESCAPE_CHARS)
@@ -128,7 +131,7 @@ def extract_bullet_points(content: str) -> list[str]:
     return _tree_bullet_points(document)
 
 
-def _type_from_heading(heading: Heading) -> str:
+def _type_from_heading(heading: Heading) -> HTag:
     if heading.level in [1, 2, 3, 4, 5, 6]:
         return f"h{heading.level}"
     else:
@@ -174,6 +177,43 @@ def find_markdown_text(
         pos = match.end()
 
 
+def extract_headings(text: str) -> list[tuple[HTag, str]]:
+    """
+    Extract all Markdown headings from the given content.
+    Returns a list of (tag, text) tuples:
+    [("h1", "Main Title"), ("h2", "Subtitle")]
+    where `#` corresponds to `h1`, `##` to `h2`, etc.
+    """
+    document = marko.parse(text)
+    headings_list: list[tuple[HTag, str]] = []
+
+    def _collect_headings_recursive(element: Any) -> None:
+        if isinstance(element, Heading):
+            tag = _type_from_heading(element)
+            content = _extract_text(element).strip()
+            headings_list.append((tag, content))
+
+        if hasattr(element, "children"):
+            for child in element.children:
+                _collect_headings_recursive(child)
+
+    _collect_headings_recursive(document)
+
+    return headings_list
+
+
+def first_heading(text: str, *, allowed_tags: tuple[HTag, ...] = ("h1", "h2")) -> str | None:
+    """
+    Find the text of the first heading. Returns first h1 if present, otherwise first h2, etc.
+    """
+    headings = extract_headings(text)
+    for goal_tag in allowed_tags:
+        for h_tag, h_text in headings:
+            if h_tag == goal_tag:
+                return h_text
+    return None
+
+
 ## Tests
 
 
@@ -224,3 +264,44 @@ def test_find_markdown_text() -> None:  # pragma: no cover
     pattern = re.compile("bar", re.IGNORECASE)
     match = find_markdown_text(pattern, text)
     assert match is None
+
+
+def test_extract_headings_and_first_header() -> None:
+    markdown_content = dedent("""
+        # Title 1
+        Some text.
+        ## Subtitle 1.1
+        More text.
+        ### Sub-subtitle 1.1.1
+        Even more text.
+        # Title 2 *with formatting*
+        And final text.
+        ## Subtitle 2.1
+        """)
+    expected_headings = [
+        ("h1", "Title 1"),
+        ("h2", "Subtitle 1.1"),
+        ("h3", "Sub-subtitle 1.1.1"),
+        ("h1", "Title 2 with formatting"),
+        ("h2", "Subtitle 2.1"),
+    ]
+    assert extract_headings(markdown_content) == expected_headings
+
+    assert first_heading(markdown_content) == "Title 1"
+    assert first_heading(markdown_content) == "Title 1"
+    assert first_heading(markdown_content, allowed_tags=("h2",)) == "Subtitle 1.1"
+    assert first_heading(markdown_content, allowed_tags=("h3",)) == "Sub-subtitle 1.1.1"
+    assert first_heading(markdown_content, allowed_tags=("h4",)) is None
+
+    assert extract_headings("") == []
+    assert first_heading("") is None
+    assert first_heading("Just text, no headers.") is None
+
+    markdown_h2_only = "## Only H2 Here"
+    assert extract_headings(markdown_h2_only) == [("h2", "Only H2 Here")]
+    assert first_heading(markdown_h2_only) == "Only H2 Here"
+    assert first_heading(markdown_h2_only, allowed_tags=("h2",)) == "Only H2 Here"
+
+    formatted_header_md = "## *Formatted* _Header_ [link](#anchor)"
+    assert extract_headings(formatted_header_md) == [("h2", "Formatted Header link")]
+    assert first_heading(formatted_header_md, allowed_tags=("h2",)) == "Formatted Header link"

kash/utils/common/format_utils.py

@@ -2,10 +2,9 @@ import html
 import re
 from pathlib import Path
 
-from inflect import engine
 from prettyfmt import fmt_path
 
-from kash.utils.common.lazyobject import lazyobject
+from kash.utils.common.inflection import plural
 from kash.utils.common.url import Locator, is_url
 
 
@@ -45,16 +44,11 @@ def fmt_loc(locator: str | Locator, resolve: bool = True) -> str:
         return fmt_path(locator, resolve=resolve)
 
 
-@lazyobject
-def inflect():
-    return engine()
-
-
 def fmt_count_items(count: int, name: str = "item") -> str:
     """
     Format a count and a name as a pluralized phrase, e.g. "1 item" or "2 items".
     """
-    return f"{count} {inflect.plural(name, count)}"  # pyright: ignore
+    return f"{count} {plural(name, count)}"  # pyright: ignore
 
 
 ## Tests

kash/utils/common/inflection.py

@@ -0,0 +1,22 @@
+from functools import cache
+
+# Had been using the `inflect` package, but it takes over 1s to import.
+# pluralizer seems simpler and fine for common English usage.
+
+
+@cache
+def _get_pluralizer():
+    from pluralizer import Pluralizer
+
+    return Pluralizer()
+
+
+def plural(word: str, count: int | None = None) -> str:
+    """
+    Pluralize or singularize a word based on the count.
+    """
+    from chopdiff.docs import is_word
+
+    if not is_word(word):
+        return word
+    return _get_pluralizer().pluralize(word, count=count)

kash/utils/common/task_stack.py

@@ -3,7 +3,6 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 
 from kash.config.text_styles import (
-    EMOJI_ACTION,
     EMOJI_BREADCRUMB_SEP,
     EMOJI_MSG_INDENT,
     TASK_STACK_HEADER,
@@ -93,9 +92,8 @@ class TaskStack:
         if not self.stack:
             return ""
         else:
-            prefix = f"{self.prefix_str()} {EMOJI_BREADCRUMB_SEP} "
-            sep = f"\n{prefix}"
-            return prefix + sep.join(state.full_str() for state in self.stack)
+            sep = f" {EMOJI_BREADCRUMB_SEP} "
+            return f"{EMOJI_BREADCRUMB_SEP} " + sep.join(state.full_str() for state in self.stack)
 
     def prefix_str(self) -> str:
         if not self.stack:
@@ -107,8 +105,7 @@ class TaskStack:
         return f"TaskStack({self.full_str()})"
 
     def log_stack(self):
-        self._print()
-        self._log.message(f"{EMOJI_ACTION} {TASK_STACK_HEADER}\n%s", self.full_str())
+        self._log.message(f"{TASK_STACK_HEADER} %s", self.full_str())
 
     @contextmanager
     def context(self, name: str, total_parts: int = 1, unit: str = ""):
@@ -123,9 +120,7 @@ class TaskStack:
         except Exception as e:
             # Log immediately where the exception occurred, but don't double-log.
             if e not in self.exceptions_logged:
-                self._log.warning(
-                    "Exception in task context: %s: %s", type(e).__name__, e, exc_info=True
-                )
+                self._log.info("Exception in task context: %s: %s", type(e).__name__, e)
                 self.exceptions_logged.add(e)
             self.next(last_had_error=True)
             raise
@@ -139,12 +134,6 @@ class TaskStack:
 
         return get_logger(__name__)
 
-    @property
-    def _print(self):
-        from kash.shell.output.shell_output import cprint
-
-        return cprint
-
 
 task_stack_var: contextvars.ContextVar[TaskStack | None] = contextvars.ContextVar(
     "task_stack", default=None

kash/utils/errors.py

@@ -3,6 +3,8 @@ Common hierarchy of error types. These inherit from standard errors like
 ValueError and FileExistsError but are more fine-grained.
 """
 
+from functools import cache
+
 
 class KashRuntimeError(ValueError):
     """Base class for kash runtime errors."""
@@ -145,8 +147,14 @@ class ApiError(KashRuntimeError):
     pass
 
 
-def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
+@cache
+def get_nonfatal_exceptions() -> tuple[type[Exception], ...]:
+    """
+    Exceptions that are not fatal and usually don't merit a full stack trace.
+    """
     exceptions: list[type[Exception]] = [SelfExplanatoryError, FileNotFoundError, IOError]
+
+    # Slow imports, do lazily.
     try:
         from xonsh.tools import XonshError
 
@@ -155,14 +163,15 @@ def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
         pass
 
     try:
-        import litellm
+        import openai
 
-        exceptions.append(litellm.exceptions.APIError)
+        # LiteLLM exceptions subclass openai.APIError
+        exceptions.append(openai.APIError)
     except ImportError:
         pass
 
     try:
-        import yt_dlp
+        import yt_dlp.utils
 
         exceptions.append(yt_dlp.utils.DownloadError)
     except ImportError:
@@ -171,12 +180,8 @@ def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
     return tuple(exceptions)
 
 
-NONFATAL_EXCEPTIONS = _nonfatal_exceptions()
-"""Exceptions that are not fatal and usually don't merit a full stack trace."""
-
-
 def is_fatal(exception: Exception) -> bool:
-    for e in NONFATAL_EXCEPTIONS:
+    for e in get_nonfatal_exceptions():
         if isinstance(exception, e):
             return False
     return True

kash/utils/file_utils/file_formats_model.py

@@ -103,6 +103,13 @@ class Format(Enum):
             self.log,
         ]
 
+    @property
+    def is_simple_text(self) -> bool:
+        """
+        Is this plaintext or close to it, like Markdown?
+        """
+        return self in [self.plaintext, self.markdown, self.md_html]
+
     @property
     def is_doc(self) -> bool:
         return self in [
@@ -130,6 +137,14 @@ class Format(Enum):
     def is_code(self) -> bool:
         return self in [self.python, self.shellscript, self.xonsh, self.json, self.yaml]
 
+    @property
+    def is_markdown(self) -> bool:
+        return self in [self.markdown, self.md_html]
+
+    @property
+    def is_html(self) -> bool:
+        return self in [self.html, self.md_html]
+
     @property
     def is_data(self) -> bool:
         return self in [self.csv, self.xlsx, self.npz]

kash/utils/file_utils/file_sort_filter.py

@@ -1,9 +1,11 @@
+from __future__ import annotations
+
 from datetime import UTC, datetime
 from enum import Enum
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import humanfriendly
-import pandas as pd
 from funlog import log_calls
 from prettyfmt import fmt_path
 from pydantic.dataclasses import dataclass
@@ -12,6 +14,9 @@ from kash.config.logger import get_logger
 from kash.utils.errors import FileNotFound, InvalidInput
 from kash.utils.file_utils.file_walk import IgnoreFilter, walk_by_dir
 
+if TYPE_CHECKING:
+    from pandas import DataFrame
+
 log = get_logger(__name__)
 
 
@@ -122,8 +127,10 @@ class FileListing:
     size_matching: int
     since_timestamp: float
 
-    def as_dataframe(self) -> pd.DataFrame:
-        df = pd.DataFrame([file.__dict__ for file in self.files])
+    def as_dataframe(self) -> DataFrame:
+        from pandas import DataFrame
+
+        df = DataFrame([file.__dict__ for file in self.files])
         return df
 
     @property

kash/web_gen/templates/base_styles.css.jinja

@@ -83,6 +83,9 @@ body {
 p {
   margin-bottom: 1rem;
 }
+pre {
+  margin-bottom: 1rem;
+}
 
 b, strong {
   font-weight: var(--font-weight-sans-bold);
@@ -114,14 +117,14 @@ h1 {
 
 h2 {
   font-size: 1.4rem;
-  margin-top: 2.5rem;
+  margin-top: 1.2rem;
   margin-bottom: 1rem;
 }
 
 h3 {
   font-size: 1.09rem;
-  margin-top: 1.7rem;
-  margin-bottom: 0.7rem;
+  margin-top: 1.5rem;
+  margin-bottom: 0.5rem;
 }
 
 h4 {
@@ -289,6 +292,8 @@ sup {
   padding: 0 0.15rem;
   border-radius: 4px;
   transition: all 0.15s ease-in-out;
+  font-style: normal;
+  font-weight: normal;
 }
 
 .footnote-ref a:hover, .footnote:hover {

kash/workspaces/__init__.py

@@ -1,19 +1,28 @@
 from kash.workspaces.selections import Selection, SelectionHistory
+from kash.workspaces.workspace_dirs import (
+    enclosing_ws_dir,
+    global_ws_dir,
+    is_global_ws_dir,
+    is_ws_dir,
+)
 from kash.workspaces.workspaces import (
     Workspace,
+    _switch_ws_settings,
     current_ignore,
     current_ws,
     get_global_ws,
     get_ws,
-    global_ws_dir,
     resolve_ws,
-    switch_to_ws,
     ws_param_value,
 )
 
 __all__ = [
     "Selection",
     "SelectionHistory",
+    "enclosing_ws_dir",
+    "global_ws_dir",
+    "is_global_ws_dir",
+    "is_ws_dir",
     "Workspace",
     "current_ignore",
     "current_ws",
@@ -21,6 +30,6 @@ __all__ = [
     "get_ws",
     "global_ws_dir",
     "resolve_ws",
+    "_switch_ws_settings",
     "ws_param_value",
-    "switch_to_ws",
 ]

kash/workspaces/workspace_dirs.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from functools import cache
+from pathlib import Path
+
+from kash.config.logger import get_logger
+from kash.config.settings import global_settings, resolve_and_create_dirs
+from kash.file_storage.metadata_dirs import MetadataDirs
+from kash.utils.errors import InvalidInput
+
+log = get_logger(__name__)
+
+
+@cache
+def global_ws_dir() -> Path:
+    kb_path = resolve_and_create_dirs(global_settings().global_ws_dir, is_dir=True)
+    log.debug("Global workspace path: %s", kb_path)
+    return kb_path
+
+
+def is_global_ws_dir(path: Path) -> bool:
+    return path.resolve() == global_settings().global_ws_dir
+
+
+def is_ws_dir(path: Path) -> bool:
+    dirs = MetadataDirs(path, False)
+    return dirs.is_initialized()
+
+
+def enclosing_ws_dir(path: Path | None = None) -> Path | None:
+    """
+    Get the workspace directory enclosing the given path, or of the current
+    working directory if no path is given.
+    """
+    if not path:
+        path = Path(".")
+
+    path = path.absolute()
+    while path != Path("/"):
+        if is_ws_dir(path):
+            return path
+        path = path.parent
+
+    return None
+
+
+def normalize_workspace_name(ws_name: str) -> str:
+    return str(ws_name).strip().rstrip("/")
+
+
+def check_strict_workspace_name(ws_name: str) -> str:
+    ws_name = normalize_workspace_name(ws_name)
+    if not re.match(r"^[\w.-]+$", ws_name):
+        raise InvalidInput(
+            f"Use an alphanumeric name (- and . also allowed) for the workspace name: `{ws_name}`"
+        )
+    return ws_name

kash/workspaces/workspace_importing.py

@@ -45,7 +45,7 @@ def import_and_load(ws: FileStore, locator: Locator | str) -> Item:
             # It's already a StorePath.
             item = ws.load(locator)
         else:
-            log.message("Importing locator as local path: %r", locator)
+            log.info("Importing locator as local path: %r", locator)
             path = Path(locator)
             if not path.exists():
                 raise InvalidInput(f"File not found: {path}")

kash/workspaces/workspaces.py

@@ -1,5 +1,5 @@
-import contextvars
-import re
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from functools import cache
 from pathlib import Path
@@ -13,10 +13,13 @@ from kash.config.settings import (
     global_settings,
     resolve_and_create_dirs,
 )
+from kash.config.text_styles import STYLE_HINT
 from kash.file_storage.metadata_dirs import MetadataDirs
 from kash.model.params_model import GLOBAL_PARAMS, RawParamValues
+from kash.shell.output.shell_output import PrintHooks, cprint
 from kash.utils.errors import FileNotFound, InvalidInput, InvalidState
 from kash.utils.file_utils.ignore_files import IgnoreFilter, is_ignored_default
+from kash.workspaces.workspace_dirs import check_strict_workspace_name, is_global_ws_dir, is_ws_dir
 from kash.workspaces.workspace_registry import WorkspaceInfo, get_ws_registry
 
 if TYPE_CHECKING:
@@ -25,19 +28,6 @@ if TYPE_CHECKING:
 log = get_logger(__name__)
 
 
-def normalize_workspace_name(ws_name: str) -> str:
-    return str(ws_name).strip().rstrip("/")
-
-
-def check_strict_workspace_name(ws_name: str) -> str:
-    ws_name = normalize_workspace_name(ws_name)
-    if not re.match(r"^[\w.-]+$", ws_name):
-        raise InvalidInput(
-            f"Use an alphanumeric name (- and . also allowed) for the workspace name: `{ws_name}`"
-        )
-    return ws_name
-
-
 class Workspace(ABC):
     """
     A workspace is the context for actions and is tied to a folder on disk.
@@ -59,50 +49,6 @@ class Workspace(ABC):
     def base_dir(self) -> Path:
         """The base directory for this workspace."""
 
-    def __enter__(self):
-        """
-        Context manager to set this workspace as the current workspace.
-        """
-        from kash.workspaces.workspaces import current_ws_context
-
-        self._token = current_ws_context.set(self.base_dir)
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        """
-        Restore the previous workspace context.
-        """
-        from kash.workspaces.workspaces import current_ws_context
-
-        current_ws_context.reset(self._token)
-
-
-current_ws_context: contextvars.ContextVar[Path | None] = contextvars.ContextVar(
-    "current_ws_context", default=None
-)
-"""
-Context variable that tracks the current workspace. Only used if it is
-explicitly set with a `with ws.as_current()` block.
-"""
-
-
-def is_ws_dir(path: Path) -> bool:
-    dirs = MetadataDirs(path, False)
-    return dirs.is_initialized()
-
-
-def enclosing_ws_dir(path: Path) -> Path | None:
-    """
-    Get the workspace directory enclosing the given path (itself or a parent or None).
-    """
-    path = path.absolute()
-    while path != Path("/"):
-        if is_ws_dir(path):
-            return path
-        path = path.parent
-
-    return None
-
 
 def resolve_ws(name: str | Path) -> WorkspaceInfo:
     """
@@ -137,10 +83,10 @@ def resolve_ws(name: str | Path) -> WorkspaceInfo:
 
     ws_name = check_strict_workspace_name(resolved.name)
 
-    return WorkspaceInfo(ws_name, resolved, is_global_ws_path(resolved))
+    return WorkspaceInfo(ws_name, resolved, is_global_ws_dir(resolved))
 
 
-def get_ws(name_or_path: str | Path, auto_init: bool = True) -> "FileStore":
+def get_ws(name_or_path: str | Path, auto_init: bool = True) -> FileStore:
     """
     Get a workspace by name or path. Adds to the in-memory registry so we reuse it.
     With `auto_init` true, will initialize the workspace if it is not already initialized.
@@ -162,18 +108,14 @@ def global_ws_dir() -> Path:
     return kb_path
 
 
-def is_global_ws_path(path: Path) -> bool:
-    return path.name.lower() == GLOBAL_WS_NAME.lower()
-
-
-def get_global_ws() -> "FileStore":
+def get_global_ws() -> FileStore:
     """
     Get the global_ws workspace.
     """
     return get_ws_registry().load(GLOBAL_WS_NAME, global_ws_dir(), True)
 
 
-def switch_to_ws(base_dir: Path) -> "FileStore":
+def _switch_ws_settings(base_dir: Path) -> FileStore:
     """
     Switch the current workspace to the given directory.
     Updates logging and cache directories to be within that workspace.
@@ -199,41 +141,35 @@ def switch_to_ws(base_dir: Path) -> "FileStore":
     return get_ws_registry().load(info.name, info.base_dir, info.is_global_ws)
 
 
-def _current_ws_info() -> tuple[Path | None, bool]:
-    """
-    Infer the current workspace from context or the current working directory.
-    Does not load the workspace.
-    """
-    # First check if we have an explicit workspace context.
-    override_dir = current_ws_context.get()
-    if override_dir:
-        return override_dir, is_global_ws_path(override_dir)
-
-    # Fall back to detecting from the current working directory.
-    dir = enclosing_ws_dir(Path("."))
-    is_global_ws = is_global_ws_path(dir) if dir else False
-    if not dir or is_global_ws:
-        dir = global_ws_dir()
-    return dir, is_global_ws
-
-
-def current_ws(silent: bool = False) -> "FileStore":
+def current_ws(silent: bool = False) -> FileStore:
     """
     Get the current workspace based on the current working directory.
     Loads and registers the workspace if it is not already loaded.
-    Also updates logging and cache directories if this has changed.
+
+    As a convenience, this call also auto-updates logging and cache directories
+    if this has changed.
     """
-    base_dir, _is_global_ws = _current_ws_info()
+    from kash.exec.runtime_settings import current_ws_context
+
+    ws_context = current_ws_context()
+    base_dir = ws_context.current_ws_dir
     if not base_dir:
         raise InvalidState(
             f"No workspace found in: {fmt_path(Path('.').absolute(), resolve=False)}\n"
             "Create one with the `workspace` command."
         )
 
-    ws = switch_to_ws(base_dir)
+    ws = _switch_ws_settings(base_dir)
 
     if not silent:
-        ws.log_workspace_info(once=True)
+        did_log = ws.log_workspace_info(once=True)
+        if did_log and ws.is_global_ws and not ws_context.override_dir:
+            PrintHooks.spacer()
+            log.warning("Note you are currently using the default global workspace.")
+            cprint(
+                "Create or switch to another workspace with the `workspace` command.",
+                style=STYLE_HINT,
+            )
 
     return ws