kash-shell 0.3.17__py3-none-any.whl → 0.3.20__py3-none-any.whl

kash/exec/precondition_registry.py

@@ -39,7 +39,7 @@ def kash_precondition(func: Callable[[Item], bool]) -> Precondition:
 
 def get_all_preconditions() -> dict[str, Precondition]:
     """
-    Returns a copy of all registered preconditions.
+    Returns a copy of all registered preconditions (in alphabetical order).
     """
-    # Return a copy for safety.
-    return dict(_preconditions.copy())
+    # Return a copy for safety, sorted by key.
+    return dict(sorted(_preconditions.copy().items()))

kash/file_storage/file_store.py

@@ -83,6 +83,11 @@ class FileStore(Workspace):
     def base_dir(self) -> Path:
         return self.base_dir_path
 
+    @property
+    @override
+    def assets_dir(self) -> Path:
+        return self.base_dir / "assets"
+
     @synchronized
     @log_calls(level="warning", if_slower_than=2.0)
     def reload(self, auto_init: bool = True):
@@ -340,6 +345,18 @@ class FileStore(Workspace):
 
             return StorePath(store_path), old_store_path
 
+    def target_path_for(self, item: Item) -> Path:
+        """
+        Get an the absolute path for an item. Use this if you need to work around the
+        usual save mechanism and write directly to the store yourself, at the location
+        the item usually would be saved.
+
+        If you write to this path, then set the item's `external_path` to indicate it's
+        already saved.
+        """
+        store_path, _old_store_path = self.store_path_for(item)
+        return self.base_dir / store_path
+
     def _tmp_path_for(self, item: Item) -> StorePath:
         """
         Find a path for an item in the tmp directory.
@@ -388,6 +405,7 @@ class FileStore(Workspace):
         # If external path already exists and is within the workspace, the file was
         # already saved (e.g. by an action that wrote the item directly to the store).
         external_path = item.external_path and Path(item.external_path).resolve()
+        skipped_save = False
         if external_path and self._is_in_store(external_path):
             log.info("Item with external_path already saved: %s", fmt_loc(external_path))
             rel_path = external_path.relative_to(self.base_dir)
@@ -463,12 +481,17 @@ class FileStore(Workspace):
                     )
                     os.unlink(full_path)
                     store_path = old_store_path
+                    skipped_save = True
 
         # Update in-memory store_path only after successful save.
         item.store_path = str(store_path)
         self._id_index_item(store_path)
 
-        log.message("%s Saved item:\n%s", EMOJI_SAVED, fmt_lines([fmt_loc(store_path)]))
+        if not skipped_save:
+            log.message("%s Saved item: %s", EMOJI_SAVED, fmt_loc(store_path))
+        else:
+            log.info("%s Already saved: %s", EMOJI_SAVED, fmt_loc(store_path))
+
         return store_path
 
     @log_calls(level="debug")

kash/file_storage/store_filenames.py

@@ -30,6 +30,10 @@ def folder_for_type(item_type: ItemType) -> Path:
 
 
 def join_suffix(base_slug: str, full_suffix: str) -> str:
+    """
+    Create a store filename by joining a base slug and a full suffix, i.e. a filename
+    extension with or without an item type (`.html` or `.resource.html`, for example).
+    """
     return f"{base_slug}.{full_suffix.lstrip('.')}"
 
 

kash/help/function_param_info.py

@@ -2,9 +2,9 @@ from collections.abc import Callable
 from dataclasses import replace
 from typing import Any
 
-from kash.help.docstring_utils import parse_docstring
 from kash.model.params_model import ALL_COMMON_PARAMS, Param
 from kash.utils.common.function_inspect import FuncParam, inspect_function_params
+from kash.utils.common.parse_docstring import parse_docstring
 
 
 def _look_up_param_docs(func: Callable[..., Any], kw_params: list[FuncParam]) -> list[Param]:

kash/help/help_pages.py

@@ -3,7 +3,6 @@ from rich.text import Text
 from kash.config.logger import get_logger
 from kash.config.text_styles import STYLE_HINT
 from kash.docs.all_docs import DocSelection, all_docs
-from kash.help.docstring_utils import parse_docstring
 from kash.shell.output.shell_formatting import format_name_and_value
 from kash.shell.output.shell_output import (
     PrintHooks,
@@ -12,6 +11,7 @@ from kash.shell.output.shell_output import (
     print_hrule,
     print_markdown,
 )
+from kash.utils.common.parse_docstring import parse_docstring
 
 log = get_logger(__name__)
 

kash/help/help_printing.py

@@ -6,7 +6,6 @@ from kash.docs.all_docs import DocSelection
 from kash.exec.action_registry import look_up_action_class
 from kash.exec.command_registry import CommandFunction, look_up_command
 from kash.help.assistant import assist_preamble, assistance_unstructured
-from kash.help.docstring_utils import parse_docstring
 from kash.help.function_param_info import annotate_param_info
 from kash.help.help_lookups import look_up_faq
 from kash.help.tldr_help import tldr_help
@@ -22,6 +21,7 @@ from kash.shell.output.shell_output import (
     print_help,
     print_markdown,
 )
+from kash.utils.common.parse_docstring import parse_docstring
 from kash.utils.errors import InvalidInput, NoMatch
 from kash.utils.file_formats.chat_format import ChatHistory, ChatMessage, ChatRole
 

kash/llm_utils/llm_features.py

@@ -56,13 +56,17 @@ FEATURES = {
 }
 
 preferred_llms: list[LLMName] = [
+    LLM.o4_mini,
+    LLM.o3,
     LLM.o3_mini,
     LLM.o1_mini,
     LLM.o1,
     LLM.gpt_4o_mini,
     LLM.gpt_4o,
     LLM.gpt_4,
+    LLM.claude_4_sonnet,
+    LLM.claude_4_opus,
     LLM.claude_3_7_sonnet,
-    LLM.claude_3_5_sonnet,
     LLM.claude_3_5_haiku,
+    LLM.gemini_2_5_pro_preview_05_06,
 ]

kash/llm_utils/llms.py

@@ -13,32 +13,42 @@ class LLM(LLMName, Enum):
     """
 
     # https://platform.openai.com/docs/models
-    o1_mini = LLMName("o1-mini")
-    o1 = LLMName("o1")
+    o4_mini = LLMName("o4-mini")
     o3 = LLMName("o3")
     o3_mini = LLMName("o3-mini")
-    o4_mini = LLMName("o4-mini")
+    o1 = LLMName("o1")
+    o1_mini = LLMName("o1-mini")
+    o1_pro = LLMName("o1-pro")
     o1_preview = LLMName("o1-preview")
-    gpt_4o_mini = LLMName("gpt-4o-mini")
+    gpt_4_1 = LLMName("gpt-4.1")
     gpt_4o = LLMName("gpt-4o")
+    gpt_4o_mini = LLMName("gpt-4o-mini")
     gpt_4 = LLMName("gpt-4")
-    gpt_4_1 = LLMName("gpt-4.1")
+
     gpt_4_1_mini = LLMName("gpt-4.1-mini")
     gpt_4_1_nano = LLMName("gpt-4.1-nano")
 
     # https://docs.anthropic.com/en/docs/about-claude/models/all-models
+    claude_4_opus = LLMName("claude-opus-4-20250514")
+    claude_4_sonnet = LLMName("claude-sonnet-4-20250514")
     claude_3_7_sonnet = LLMName("claude-3-7-sonnet-latest")
-    claude_3_5_sonnet = LLMName("claude-3-5-sonnet-latest")
     claude_3_5_haiku = LLMName("claude-3-5-haiku-latest")
 
     # https://ai.google.dev/gemini-api/docs/models
-    gemini_2_5_pro_exp_03_25 = LLMName("gemini/gemini-2.5-pro-exp-03-25")
+    gemini_2_5_pro_preview_06_05 = LLMName("gemini/gemini-2.5-pro-preview-06-05")
+    gemini_2_5_pro_preview_05_06 = LLMName("gemini/gemini-2.5-pro-preview-05-06")
+    gemini_2_5_pro_preview_03_25 = LLMName("gemini/gemini-2.5-pro-preview-03-25")
+    gemini_2_5_flash_preview = LLMName("gemini-2.5-flash-preview-05-20")
     gemini_2_0_flash = LLMName("gemini/gemini-2_0-flash")
     gemini_2_0_flash_lite = LLMName("gemini/gemini-2.0-flash-lite")
     gemini_2_0_pro_exp_02_05 = LLMName("gemini/gemini-2.0-pro-exp-02-05")
 
     # https://docs.x.ai/docs/models
-    xai_grok_2 = LLMName("xai/grok-2-latest")
+    xai_grok_3 = LLMName("xai/grok-3")
+    xai_grok_3_fast = LLMName("xai/grok-3-fast")
+    xai_grok_3_mini = LLMName("xai/grok-3-mini")
+    xai_grok_3_mini_fast = LLMName("xai/grok-3-mini-fast")
+    xai_grok_2 = LLMName("xai/grok-2")
 
     # https://api-docs.deepseek.com/quick_start/pricing
     deepseek_chat = LLMName("deepseek/deepseek-chat")

kash/media_base/media_cache.py

@@ -3,6 +3,7 @@ from functools import cache
 from pathlib import Path
 
 from prettyfmt import fmt_lines, fmt_path
+from prettyfmt.prettyfmt import fmt_size_dual
 from strif import atomic_output_file
 
 from kash.config.logger import get_logger
@@ -14,6 +15,7 @@ from kash.media_base.media_services import (
 )
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url, as_file_url, is_url
+from kash.utils.common.url_slice import parse_url_slice
 from kash.utils.errors import FileNotFound, InvalidInput, UnexpectedError
 from kash.utils.file_utils.file_formats_model import MediaType
 from kash.web_content.dir_store import DirStore
@@ -51,14 +53,16 @@ class MediaCache(DirStore):
         super().__init__(root)
 
     def _write_transcript(self, url: Url, content: str) -> None:
-        transcript_path = self.path_for(url, suffix=SUFFIX_TRANSCRIPT)
+        key = str(url)  # Cache key is the URL (with slice fragment if present)
+        transcript_path = self.path_for(key, suffix=SUFFIX_TRANSCRIPT)
         with atomic_output_file(transcript_path) as temp_output:
             with open(temp_output, "w") as f:
                 f.write(content)
         log.message("Transcript saved to cache: %s", fmt_path(transcript_path))
 
     def _read_transcript(self, url: Url) -> str | None:
-        transcript_file = self.find(url, suffix=SUFFIX_TRANSCRIPT)
+        key = str(url)  # Cache key is the URL (with slice fragment if present)
+        transcript_file = self.find(key, suffix=SUFFIX_TRANSCRIPT)
         if transcript_file:
             log.message("Video transcript already in cache: %s: %s", url, fmt_path(transcript_file))
             with open(transcript_file) as f:
@@ -66,12 +70,13 @@ class MediaCache(DirStore):
         return None
 
     def _downsample_audio(self, url: Url) -> Path:
-        downsampled_audio_file = self.find(url, suffix=SUFFIX_16KMP3)
+        key = str(url)  # Cache key is the URL (with slice fragment if present)
+        downsampled_audio_file = self.find(key, suffix=SUFFIX_16KMP3)
         if not downsampled_audio_file:
-            full_audio_file = self.find(url, suffix=SUFFIX_MP3)
+            full_audio_file = self.find(key, suffix=SUFFIX_MP3)
             if not full_audio_file:
                 raise ValueError("No audio file found for: %s" % url)
-            downsampled_audio_file = self.path_for(url, suffix=SUFFIX_16KMP3)
+            downsampled_audio_file = self.path_for(key, suffix=SUFFIX_16KMP3)
             log.message(
                 "Downsampling audio: %s -> %s",
                 fmt_path(full_audio_file),
@@ -95,13 +100,18 @@ class MediaCache(DirStore):
         return transcript
 
     def cache(
-        self, url: Url, refetch=False, media_types: list[MediaType] | None = None
+        self, url_or_slice: Url, refetch=False, media_types: list[MediaType] | None = None
     ) -> dict[MediaType, Path]:
         """
         Cache the media files for the given media URL. Returns paths to cached copies
         for each media type (video or audio). Returns cached copies if available,
         unless `refetch` is True.
         """
+        key = str(url_or_slice)  # Cache key is the URL (with slice fragment if present)
+
+        # Extract base URL and slice information
+        base_url, slice = parse_url_slice(url_or_slice)
+
         cached_paths: dict[MediaType, Path] = {}
 
         if not media_types:
@@ -109,14 +119,18 @@ class MediaCache(DirStore):
 
         if not refetch:
             if MediaType.audio in media_types:
-                audio_file = self.find(url, suffix=SUFFIX_MP3)
+                audio_file = self.find(key, suffix=SUFFIX_MP3)
                 if audio_file:
-                    log.message("Audio already in cache: %s: %s", url, fmt_path(audio_file))
+                    log.message(
+                        "Audio already in cache: %s: %s", url_or_slice, fmt_path(audio_file)
+                    )
                     cached_paths[MediaType.audio] = audio_file
             if MediaType.video in media_types:
-                video_file = self.find(url, suffix=SUFFIX_MP4)
+                video_file = self.find(key, suffix=SUFFIX_MP4)
                 if video_file:
-                    log.message("Video already in cache: %s: %s", url, fmt_path(video_file))
+                    log.message(
+                        "Video already in cache: %s: %s", url_or_slice, fmt_path(video_file)
+                    )
                     cached_paths[MediaType.video] = video_file
             if set(media_types).issubset(cached_paths.keys()):
                 return cached_paths
@@ -127,23 +141,30 @@ class MediaCache(DirStore):
                     [t.name for t in cached_paths.keys()],
                 )
 
-        log.message("Downloading media: %s", url)
-        media_paths = download_media_by_service(url, self.root, media_types)
+        log.message("Downloading media: %s", url_or_slice)
+        media_paths = download_media_by_service(
+            base_url, self.root, media_types=media_types, slice=slice
+        )
         if MediaType.audio in media_paths:
-            audio_path = self.path_for(url, suffix=SUFFIX_MP3)
+            audio_path = self.path_for(key, suffix=SUFFIX_MP3)
             os.rename(media_paths[MediaType.audio], audio_path)
             cached_paths[MediaType.audio] = audio_path
         if MediaType.video in media_paths:
-            video_path = self.path_for(url, suffix=SUFFIX_MP4)
+            video_path = self.path_for(key, suffix=SUFFIX_MP4)
             os.rename(media_paths[MediaType.video], video_path)
             cached_paths[MediaType.video] = video_path
 
         log.message(
             "Downloaded media and saved to cache:\n%s",
-            fmt_lines([f"{t.name}: {fmt_path(p)}" for (t, p) in cached_paths.items()]),
+            fmt_lines(
+                [
+                    f"{t.name}: {fmt_size_dual(p.stat().st_size)}: {fmt_path(p)} "
+                    for (t, p) in cached_paths.items()
+                ]
+            ),
         )
 
-        self._downsample_audio(url)
+        self._downsample_audio(url_or_slice)
 
         return cached_paths
 
@@ -156,30 +177,33 @@ class MediaCache(DirStore):
         """
         if not isinstance(url_or_path, Path) and is_url(url_or_path):
             # If it is a URL, cache it locally.
-            url = url_or_path
-            url = canonicalize_media_url(url)
-            if not url:
+            url_or_slice = url_or_path
+            # Canonicalize the URL (preserving slice information if present)
+            canon = canonicalize_media_url(url_or_slice)
+            if not canon:
                 log.error("Unrecognized media, current services: %s", get_media_services())
                 raise InvalidInput(
                     "Unrecognized media URL (is this media service configured?): %s" % url_or_path
                 )
+            url_or_slice = canon
+
             if not refetch:
-                transcript = self._read_transcript(url)
+                transcript = self._read_transcript(url_or_slice)
                 if transcript:
                     return transcript
             # Cache all formats since we usually will want them.
-            self.cache(url, refetch)
+            self.cache(url_or_slice, refetch)
         elif isinstance(url_or_path, Path):
             # Treat local media files as file:// URLs.
             # Don't need to cache originals but we still will cache audio and transcriptions.
             if not url_or_path.exists():
                 raise FileNotFound(f"File not found: {fmt_loc(url_or_path)}")
-            url = as_file_url(url_or_path)
+            url_or_slice = as_file_url(url_or_path)
         else:
             raise InvalidInput(f"Not a media URL or path: {fmt_loc(url_or_path)}")
 
         # Now do the transcription.
-        transcript = self._do_transcription(url, language=language)
+        transcript = self._do_transcription(url_or_slice, language=language)
         if not transcript:
-            raise UnexpectedError("No transcript found for: %s" % url)
+            raise UnexpectedError("No transcript found for: %s" % url_or_slice)
         return transcript

kash/media_base/media_services.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import logging
 from pathlib import Path
 
@@ -7,6 +9,7 @@ from strif import AtomicVar
 from kash.media_base.services.local_file_media import LocalFileMedia
 from kash.model.media_model import MediaMetadata, MediaService
 from kash.utils.common.url import Url
+from kash.utils.common.url_slice import Slice, add_slice_to_url, parse_url_slice
 from kash.utils.errors import InvalidInput
 from kash.utils.file_utils.file_formats_model import MediaType
 
@@ -32,14 +35,22 @@ def register_media_service(*services: MediaService) -> None:
     _media_services.update(lambda services: services + new_services)
 
 
-def canonicalize_media_url(url: Url) -> Url | None:
+def canonicalize_media_url(url_or_slice: Url) -> Url | None:
     """
     Return the canonical form of a media URL from a supported service (like YouTube).
+    Preserves any slice information in URL fragments.
     """
+    base_url, slice = parse_url_slice(url_or_slice)
+
+    # Canonicalize the base URL
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return canonical_url
+            # Add slice back to canonical URL if it existed
+            if slice:
+                return add_slice_to_url(canonical_url, slice)
+            else:
+                return canonical_url
     return None
 
 
@@ -51,10 +62,11 @@ def thumbnail_media_url(url: Url) -> Url | None:
     """
     Return a URL that links to the thumbnail of the media.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return service.thumbnail_url(url)
+            return service.thumbnail_url(base_url)
     return None
 
 
@@ -62,18 +74,21 @@ def timestamp_media_url(url: Url, timestamp: float) -> Url:
     """
     Return a URL that links to the media at the given timestamp.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return service.timestamp_url(url, timestamp)
+            return service.timestamp_url(base_url, timestamp)
     raise InvalidInput(f"Unrecognized media URL: {url}")
 
 
 def get_media_id(url: Url | None) -> str | None:
     if not url:
         return None
+
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        media_id = service.get_media_id(url)
+        media_id = service.get_media_id(base_url)
         if media_id:
             return media_id
     return None
@@ -84,10 +99,11 @@ def get_media_metadata(url: Url) -> MediaMetadata | None:
     """
     Return metadata for the media at the given URL.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        media_id = service.get_media_id(url)
+        media_id = service.get_media_id(base_url)
         if media_id:  # This is an actual video, not a channel etc.
-            return service.metadata(url)
+            return service.metadata(base_url)
     return None
 
 
@@ -95,18 +111,51 @@ def list_channel_items(url: Url) -> list[MediaMetadata]:
     """
     List all items in a channel.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return service.list_channel_items(url)
+            return service.list_channel_items(base_url)
     raise InvalidInput(f"Unrecognized media URL: {url}")
 
 
 def download_media_by_service(
-    url: Url, target_dir: Path, media_types: list[MediaType] | None = None
+    url: Url,
+    target_dir: Path,
+    *,
+    media_types: list[MediaType] | None = None,
+    slice: Slice | None = None,
 ) -> dict[MediaType, Path]:
     for service in _media_services.copy():
         canonical_url = service.canonicalize(url)
         if canonical_url:
-            return service.download_media(url, target_dir, media_types=media_types)
+            return service.download_media(url, target_dir, media_types=media_types, slice=slice)
     raise ValueError(f"Unrecognized media URL: {url}")
+
+
+## Tests
+
+
+def test_canonicalize_media_url_preserves_slice():
+    """Test that canonicalize_media_url preserves URL slice fragments."""
+
+    # Test with unrecognized URLs (should return None)
+    # This tests the slice extraction/reconstruction logic without requiring actual files
+    unrecognized_url = Url("https://unknown-service.com/video#~slice=10-30")
+    canonical_unknown = canonicalize_media_url(unrecognized_url)
+    assert canonical_unknown is None
+
+    # Test typical YouTube URL with slice (would work if YouTube service was registered)
+    youtube_url = Url("https://www.youtube.com/watch?v=dQw4w9WgXcQ#~slice=10-30")
+    # For now this returns None since YouTube service isn't registered in this test
+    # but the slice extraction/reconstruction logic is tested in url_slice.py
+    youtube_canonical = canonicalize_media_url(youtube_url)
+    assert youtube_canonical is None  # No YouTube service registered
+
+    # Test HH:MM:SS format slice
+    hms_youtube_url = Url("https://www.youtube.com/watch?v=dQw4w9WgXcQ#~slice=01:30-02:45")
+    canonical_hms = canonicalize_media_url(hms_youtube_url)
+    assert canonical_hms is None  # No YouTube service registered
+
+    # The actual slice functionality is thoroughly tested in url_slice.py
+    # This test ensures canonicalize_media_url doesn't break with slice URLs

kash/media_base/services/local_file_media.py

@@ -13,6 +13,7 @@ from kash.file_storage.store_filenames import parse_item_filename
 from kash.model.media_model import MediaMetadata, MediaService, MediaUrlType
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url
+from kash.utils.common.url_slice import Slice
 from kash.utils.errors import FileNotFound, InvalidInput
 from kash.utils.file_utils.file_formats_model import FileExt, MediaType
 
@@ -73,11 +74,18 @@ class LocalFileMedia(MediaService):
 
     @override
     def download_media(
-        self, url: Url, target_dir: Path, media_types: list[MediaType] | None = None
+        self,
+        url: Url,
+        target_dir: Path,
+        *,
+        media_types: list[MediaType] | None = None,
+        slice: Slice | None = None,
     ) -> dict[MediaType, Path]:
         path = self._parse_file_url(url)
         if not path:
             raise InvalidInput(f"Not a local file URL: {url}")
+        if slice:
+            raise NotImplementedError("Slicing currently not supported for local files")
 
         _name, _item_type, format, file_ext = parse_item_filename(path)
         os.makedirs(target_dir, exist_ok=True)

kash/model/items_model.py

@@ -675,9 +675,21 @@ class Item:
             raise FileFormatError(f"Config item is not YAML: {self.format}: {self}")
         return from_yaml_string(self.body)
 
+    def get_filename(self) -> str | None:
+        """
+        Get the store or external path filename of the item, including the
+        file extension.
+        """
+        if self.store_path:
+            return Path(self.store_path).name
+        elif self.external_path:
+            return Path(self.external_path).name
+        else:
+            return None
+
     def get_file_ext(self) -> FileExt:
         """
-        Get or infer file extension.
+        Get or infer the base file extension for the item.
         """
         if self.file_ext:
             return self.file_ext
@@ -688,7 +700,8 @@ class Item:
 
     def get_full_suffix(self) -> str:
         """
-        Get the full file extension suffix (e.g. "note.md") for this item.
+        Assemble the full file extension suffix (e.g. "resource.yml") for this item.
+        Without a leading dot.
         """
         if self.type == ItemType.extension:
             # Python files cannot have more than one . in them.
@@ -892,12 +905,14 @@ class Item:
 
     def fmt_loc(self) -> str:
         """
-        Formatted store path, external path, or title. For error messages etc.
+        Formatted store path, external path, URL, or title. Use for logging etc.
         """
         if self.store_path:
             return fmt_store_path(self.store_path)
         elif self.external_path:
             return fmt_loc(self.external_path)
+        elif self.url:
+            return fmt_loc(self.url)
         else:
             return repr(self.pick_title())
 
@@ -915,10 +930,10 @@ class Item:
                 key_filter={
                     "store_path": 0,
                     "type": 64,
-                    "title": 64,
+                    "format": 64,
+                    "title": 40,
                     "url": 64,
                     "external_path": 64,
-                    "context": 64,
                 },
             )
             + f"[{len(self.body) if self.body else 0} body chars]"
@@ -932,13 +947,12 @@ class Item:
                     "store_path": 0,
                     "external_path": 64,
                     "type": 64,
+                    "format": 64,
                     "state": 64,
-                    "title": 64,
+                    "title": 40,
                     "url": 64,
-                    "format": 64,
                     "created_at": 64,
                     "body": 64,
-                    "context": 64,
                 },
             )
             + f"[{len(self.body) if self.body else 0} body chars]"

kash/model/media_model.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from datetime import date
 from enum import Enum
@@ -7,6 +9,7 @@ from prettyfmt import abbrev_obj
 from pydantic.dataclasses import dataclass
 
 from kash.utils.common.url import Url
+from kash.utils.common.url_slice import Slice
 from kash.utils.file_utils.file_formats_model import MediaType
 
 
@@ -109,7 +112,12 @@ class MediaService(ABC):
 
     @abstractmethod
     def download_media(
-        self, url: Url, target_dir: Path, media_types: list[MediaType] | None = None
+        self,
+        url: Url,
+        target_dir: Path,
+        *,
+        media_types: list[MediaType] | None = None,
+        slice: Slice | None = None,
     ) -> dict[MediaType, Path]:
         """
         Download media from URL and extract to audio or video formats.