kash-shell 0.3.18__tar.gz → 0.3.20__tar.gz

{kash_shell-0.3.18 → kash_shell-0.3.20}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier. Do not edit manually.
-_commit: v0.2.10
+_commit: v0.2.13
 _src_path: gh:jlevy/simple-modern-uv
 package_author_email: joshua@cal.berkeley.edu
 package_author_name: Joshua Levy

{kash_shell-0.3.18 → kash_shell-0.3.20}/.cursor/rules/python.mdc

@@ -16,10 +16,10 @@ Always use full type annotations, generics, and other modern practices.
 
 ## Project Setup and Developer Workflows
 
-- This project has a modern pyproject.toml file and a Makefile.
-  Be sure you read and understand both.
+- Important: BE SURE you read and understand the project setup by reading the
+  pyproject.toml file and the Makefile.
 
-- Use uv for running all code and managing dependencies.
+- ALWAYS use uv for running all code and managing dependencies.
   Never use direct `pip` or `python` commands.
 
 - Use modern uv commands: `uv sync`, `uv run ...`, etc.
@@ -56,10 +56,13 @@ Always use full type annotations, generics, and other modern practices.
 - Be sure to resolve the pyright (basedpyright) linter errors as you develop and make
   changes.
 
-- If type checker errors are hard to resolve, check pyproject.toml to see if they are an
-  excessively pedantic error.
-  In special cases you may consider disabling it globally it in pyproject.toml but you
-  *must ask for confirmation* from the user before doing this.
+- If type checker errors are hard to resolve, you may add a comment `# pyright: ignore`
+  to disable Pyright warnings or errors but ONLY if you know they are not a real problem
+  and are difficult to fix.
+
+- In special cases you may consider disabling it globally it in pyproject.toml but YOU
+  MUST ASK FOR CONFIRMATION from the user before globally disabling lint or type checker
+  rules.
 
 - Never change an existing comment, pydoc, or a log statement, unless it is directly
   fixing the issue you are changing, or the user has asked you to clean up the code.
@@ -204,8 +207,9 @@ Always use full type annotations, generics, and other modern practices.
 - Docstrings *should* mention any key rationale or pitfalls when using the class or
   function.
 
-- Don't add pydocs that just repeat information obvious from the function, variable
-  names, or concise description.
+- Avoid obvious or repetitive docstrings.
+  Do NOT add pydocs that just repeat in English facts that are obvious from the function
+  name, variable name, or types.
   That is silly and obvious and makes the code longer for no reason.
 
 - Do NOT list args and return values if they're obvious.
@@ -220,8 +224,9 @@ Always use full type annotations, generics, and other modern practices.
 
 ## General Clean Coding Practices
 
-- When writing a class DO NOT blindly make delegation methods for consistency.
-  For exmaple DO NOT write methods like this:
+- Avoid writing trivial wrapper functions.
+  For example, when writing a class DO NOT blindly make delegation methods around public
+  member variables. DO NOT write methods like this:
   ```python
       def reassemble(self) -> str:
         """Call the original reassemble method."""

{kash_shell-0.3.18 → kash_shell-0.3.20}/.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           # Update this as needed:
-          version: "0.7.11"
+          version: "0.7.13"
           enable-cache: true
           python-version: ${{ matrix.python-version }}
 

{kash_shell-0.3.18 → kash_shell-0.3.20}/.github/workflows/publish.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Install uv (official Astral action)
         uses: astral-sh/setup-uv@v5
         with:
-          version: "0.7.11"
+          version: "0.7.13"
           enable-cache: true
           python-version: "3.12"
 
@@ -43,5 +43,5 @@ jobs:
       - name: Build package
         run: uv build
 
-      - name: Publish to PyPI (using uv)
-        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

{kash_shell-0.3.18 → kash_shell-0.3.20}/Makefile

@@ -18,7 +18,10 @@ test:
 	uv run pytest
 
 test-full:
-	ENABLE_TESTS_LLM=1 ENABLE_TESTS_INTEGRATION=1 uv run pytest
+	ENABLE_TESTS_ONLINE=1 ENABLE_TESTS_INTEGRATION=1 uv run pytest
+
+run: install lint test
+	uv run kash
 
 upgrade:
 	uv sync --upgrade --all-extras --dev

{kash_shell-0.3.18 → kash_shell-0.3.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kash-shell
-Version: 0.3.18
+Version: 0.3.20
 Summary: The knowledge agent shell (core)
 Project-URL: Repository, https://github.com/jlevy/kash-shell
 Author-email: Joshua Levy <joshua@cal.berkeley.edu>
@@ -115,7 +115,7 @@ the Python framework, a few core utilities, and the Kash command-line shell.
 Additional actions for handling more complex tasks like converting documents and
 transcribing, researching, or annotating videos, are in the
 [kash-docs](https://github.com/jlevy/kash-docs) and
-[kash-media](https://github.com/jlevy/kash-docs) packages, all available on PyPI and
+[kash-media](https://github.com/jlevy/kash-media) packages, all available on PyPI and
 quick to install via uv.
 
 ### Key Concepts

{kash_shell-0.3.18 → kash_shell-0.3.20}/README.md

@@ -43,7 +43,7 @@ the Python framework, a few core utilities, and the Kash command-line shell.
 Additional actions for handling more complex tasks like converting documents and
 transcribing, researching, or annotating videos, are in the
 [kash-docs](https://github.com/jlevy/kash-docs) and
-[kash-media](https://github.com/jlevy/kash-docs) packages, all available on PyPI and
+[kash-media](https://github.com/jlevy/kash-media) packages, all available on PyPI and
 quick to install via uv.
 
 ### Key Concepts

{kash_shell-0.3.18 → kash_shell-0.3.20}/development.md

@@ -21,7 +21,7 @@ The `Makefile` simply offers shortcuts to `uv` commands for developer convenienc
 # including dev dependencies and optional dependencies.
 make install
 
-# Run uv sync, lint, and test:
+# Run uv sync, lint, and test (and also generate agent rules):
 make
 
 # Build wheel:
@@ -66,6 +66,17 @@ source .venv/bin/activate
 
 See [uv docs](https://docs.astral.sh/uv/) for details.
 
+## Agent Rules
+
+See [.cursor/rules](.cursor/rules) for agent rules.
+These are written for [Cursor](https://www.cursor.com/) but are also used by other
+agents because the Makefile will generate `CLAUDE.md` and `AGENTS.md` from the same
+rules.
+
+```shell
+make agent-rules
+```
+
 ## IDE setup
 
 If you use VSCode or a fork like Cursor or Windsurf, you can install the following

kash_shell-0.3.18/src/kash/actions/core/markdownify.py → kash_shell-0.3.20/src/kash/actions/core/markdownify_html.py

@@ -11,13 +11,10 @@ from kash.web_content.web_extract_readabilipy import extract_text_readabilipy
 log = get_logger(__name__)
 
 
-@kash_action(
-    precondition=is_url_resource | has_html_body,
-    mcp_tool=True,
-)
-def markdownify(item: Item) -> Item:
+@kash_action(precondition=is_url_resource | has_html_body, mcp_tool=True)
+def markdownify_html(item: Item) -> Item:
     """
-    Converts a URL or raw HTML item to Markdown, fetching with the content
+    Converts raw HTML or the URL of an HTML page to Markdown, fetching with the content
     cache if needed. Also uses readability to clean up the HTML.
     """
 

{kash_shell-0.3.18 → kash_shell-0.3.20}/src/kash/commands/workspace/workspace_commands.py

@@ -23,14 +23,12 @@ from kash.exec import (
     resolve_locator_arg,
 )
 from kash.exec.action_registry import get_all_actions_defaults
-from kash.exec.fetch_url_metadata import fetch_url_metadata
+from kash.exec.fetch_url_items import fetch_url_item
 from kash.exec.precondition_checks import actions_matching_paths
 from kash.exec.precondition_registry import get_all_preconditions
-from kash.exec.preconditions import is_url_resource
 from kash.exec_model.shell_model import ShellResult
 from kash.local_server.local_url_formatters import local_url_formatter
 from kash.media_base import media_tools
-from kash.media_base.media_services import is_media_url
 from kash.model.items_model import Item, ItemType
 from kash.model.params_model import GLOBAL_PARAMS
 from kash.model.paths_model import StorePath, fmt_store_path
@@ -54,12 +52,11 @@ from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.obj_replace import remove_values
 from kash.utils.common.parse_key_vals import parse_key_value
 from kash.utils.common.type_utils import not_none
-from kash.utils.common.url import Url, is_url, parse_http_url
+from kash.utils.common.url import Url
 from kash.utils.errors import InvalidInput
 from kash.utils.file_formats.chat_format import tail_chat_history
 from kash.utils.file_utils.dir_info import is_nonempty_dir
 from kash.utils.file_utils.file_formats_model import Format
-from kash.utils.text_handling.doc_normalization import can_normalize
 from kash.web_content.file_cache_utils import cache_file
 from kash.workspaces import (
     current_ws,
@@ -189,85 +186,6 @@ def cache_content(*urls_or_paths: str, refetch: bool = False) -> None:
         PrintHooks.spacer()
 
 
-@kash_command
-def download(*urls_or_paths: str, refetch: bool = False, no_format: bool = False) -> ShellResult:
-    """
-    Download a URL or resource. Uses cached content if available, unless `refetch` is true.
-    Inputs can be URLs or paths to URL resources.
-    Creates both resource and document versions for text content.
-
-    :param no_format: If true, do not also normalize Markdown content.
-    """
-    ws = current_ws()
-    saved_paths = []
-
-    for url_or_path in urls_or_paths:
-        locator = resolve_locator_arg(url_or_path)
-        url: Url | None = None
-
-        # Get the URL from the locator
-        if not isinstance(locator, Path) and is_url(locator):
-            url = Url(locator)
-        elif isinstance(locator, StorePath):
-            url_item = ws.load(locator)
-            if is_url_resource(url_item):
-                url = url_item.url
-
-        if not url:
-            raise InvalidInput(f"Not a URL or URL resource: {fmt_loc(locator)}")
-
-        # Handle media URLs differently
-        if is_media_url(url):
-            log.message(
-                "URL is a media URL, so adding as a resource and will cache media: %s", fmt_loc(url)
-            )
-            store_path = ws.import_item(url, as_type=ItemType.resource, reimport=refetch)
-            saved_paths.append(store_path)
-            media_tools.cache_media(url)
-        else:
-            # Cache the content first
-            expiration_sec = 0 if refetch else None
-            cache_result = cache_file(url, expiration_sec=expiration_sec)
-            original_filename = Path(parse_http_url(url).path).name
-            mime_type = cache_result.content.headers and cache_result.content.headers.mime_type
-
-            # Create a resource item
-            resource_item = Item.from_external_path(
-                cache_result.content.path,
-                ItemType.resource,
-                url=url,
-                mime_type=mime_type,
-                original_filename=original_filename,
-            )
-            # For initial content, do not format or add frontmatter.
-            store_path = ws.save(resource_item, no_frontmatter=True, no_format=True)
-            saved_paths.append(store_path)
-            select(store_path)
-
-            # Also create a doc version for text content if we want to normalize formatting.
-            if resource_item.format and can_normalize(resource_item.format) and not no_format:
-                doc_item = Item.from_external_path(
-                    cache_result.content.path,
-                    ItemType.doc,
-                    url=url,
-                    mime_type=mime_type,
-                    original_filename=original_filename,
-                )
-                # Now use default formatting and frontmatter.
-                doc_store_path = ws.save(doc_item)
-                saved_paths.append(doc_store_path)
-                select(doc_store_path)
-
-    print_status(
-        "Downloaded %s %s:\n%s",
-        len(saved_paths),
-        plural("item", len(saved_paths)),
-        fmt_lines(saved_paths),
-    )
-
-    return ShellResult(show_selection=True)
-
-
 @kash_command
 def history(max: int = 30, raw: bool = False) -> None:
     """
@@ -536,10 +454,14 @@ def save_clipboard(
 
 
 @kash_command
-def fetch_metadata(*files_or_urls: str, refetch: bool = False) -> ShellResult:
+def fetch_url(*files_or_urls: str, refetch: bool = False) -> ShellResult:
     """
-    Fetch metadata for the given URLs or resources. Imports new URLs and saves back
-    the fetched metadata for existing resources.
+    Fetch content and metadata for the given URLs or resources, saving to the
+    current workspace.
+
+    Imports new URLs and saves back the fetched metadata for existing resources.
+    Also saves a resource item with the content of the URL, either HTML, text, or
+    of any other type.
 
     Skips items that already have a title and description, unless `refetch` is true.
     Skips (with a warning) items that are not URL resources.
@@ -552,7 +474,7 @@ def fetch_metadata(*files_or_urls: str, refetch: bool = False) -> ShellResult:
     store_paths = []
     for locator in locators:
         try:
-            fetched_item = fetch_url_metadata(locator, refetch=refetch)
+            fetched_item = fetch_url_item(locator, refetch=refetch)
             store_paths.append(fetched_item.store_path)
         except InvalidInput as e:
             log.warning(

{kash_shell-0.3.18 → kash_shell-0.3.20}/src/kash/docs/markdown/topics/a1_what_is_kash.md

@@ -34,7 +34,7 @@ the Python framework, a few core utilities, and the Kash command-line shell.
 Additional actions for handling more complex tasks like converting documents and
 transcribing, researching, or annotating videos, are in the
 [kash-docs](https://github.com/jlevy/kash-docs) and
-[kash-media](https://github.com/jlevy/kash-docs) packages, all available on PyPI and
+[kash-media](https://github.com/jlevy/kash-media) packages, all available on PyPI and
 quick to install via uv.
 
 ### Key Concepts

{kash_shell-0.3.18 → kash_shell-0.3.20}/src/kash/exec/__init__.py

@@ -1,6 +1,7 @@
 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.command_registry import kash_command
+from kash.exec.fetch_url_items import fetch_url_item, fetch_url_item_content
 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
@@ -21,6 +22,8 @@ __all__ = [
     "prepare_action_input",
     "run_action_with_shell_context",
     "kash_command",
+    "fetch_url_item",
+    "fetch_url_item_content",
     "kash_runtime",
     "current_runtime_settings",
     "import_and_register",

{kash_shell-0.3.18 → kash_shell-0.3.20}/src/kash/exec/action_exec.py

@@ -43,7 +43,7 @@ def prepare_action_input(*input_args: CommandArg, refetch: bool = False) -> Acti
     URL or file resources, either finding them in the workspace or importing them.
     Also fetches metadata for URLs if they don't already have title and description.
     """
-    from kash.exec.fetch_url_metadata import fetch_url_item_metadata
+    from kash.exec.fetch_url_items import fetch_url_item_content
 
     ws = current_ws()
 
@@ -55,7 +55,7 @@ def prepare_action_input(*input_args: CommandArg, refetch: bool = False) -> Acti
     if input_items:
         log.message("Assembling metadata for input items:\n%s", fmt_lines(input_items))
         input_items = [
-            fetch_url_item_metadata(item, refetch=refetch) if is_url_resource(item) else item
+            fetch_url_item_content(item, refetch=refetch) if is_url_resource(item) else item
             for item in input_items
         ]
 

kash_shell-0.3.18/src/kash/exec/fetch_url_metadata.py → kash_shell-0.3.20/src/kash/exec/fetch_url_items.py

@@ -11,7 +11,9 @@ from kash.utils.errors import InvalidInput
 log = get_logger(__name__)
 
 
-def fetch_url_metadata(locator: Url | StorePath, refetch: bool = False) -> Item:
+def fetch_url_item(
+    locator: Url | StorePath, *, save_content: bool = True, refetch: bool = False
+) -> Item:
     from kash.workspaces import current_ws
 
     ws = current_ws()
@@ -26,16 +28,23 @@ def fetch_url_metadata(locator: Url | StorePath, refetch: bool = False) -> Item:
     else:
         raise InvalidInput(f"Not a URL or URL resource: {fmt_loc(locator)}")
 
-    return fetch_url_item_metadata(item, refetch=refetch)
+    return fetch_url_item_content(item, save_content=save_content, refetch=refetch)
 
 
-def fetch_url_item_metadata(item: Item, refetch: bool = False) -> Item:
+def fetch_url_item_content(item: Item, *, save_content: bool = True, refetch: bool = False) -> Item:
     """
-    Fetch metadata for a URL using a media service if we recognize the URL,
-    and otherwise fetching and extracting it from the web page HTML.
+    Fetch content and metadata for a URL using a media service if we
+    recognize the URL as a known media service. Otherwise, fetch and extract the
+    metadata and content from the web page and save it to the URL item.
+
+    If `save_content` is true, a copy of the content is also saved as
+    a resource item.
+
+    The content item is returned if content was saved. Otherwise, the updated
+    URL item is returned.
     """
     from kash.web_content.canon_url import canonicalize_url
-    from kash.web_content.web_extract import fetch_extract
+    from kash.web_content.web_extract import fetch_page_content
     from kash.workspaces import current_ws
 
     ws = current_ws()
@@ -54,28 +63,47 @@ def fetch_url_item_metadata(item: Item, refetch: bool = False) -> Item:
     # Prefer fetching metadata from media using the media service if possible.
     # Data is cleaner and YouTube for example often blocks regular scraping.
     media_metadata = get_media_metadata(url)
+    url_item: Item | None = None
+    content_item: Item | None = None
     if media_metadata:
-        fetched_item = Item.from_media_metadata(media_metadata)
+        url_item = Item.from_media_metadata(media_metadata)
         # Preserve and canonicalize any slice suffix on the URL.
         _base_url, slice = parse_url_slice(item.url)
         if slice:
             new_url = add_slice_to_url(media_metadata.url, slice)
             if new_url != item.url:
                 log.message("Updated URL from metadata and added slice: %s", new_url)
-            fetched_item.url = new_url
+            url_item.url = new_url
 
-        fetched_item = item.merged_copy(fetched_item)
+        url_item = item.merged_copy(url_item)
     else:
-        page_data = fetch_extract(url, refetch=refetch)
-        fetched_item = item.new_copy_with(
+        page_data = fetch_page_content(url, refetch=refetch, cache=save_content)
+        url_item = item.new_copy_with(
             title=page_data.title or item.title,
             description=page_data.description or item.description,
             thumbnail_url=page_data.thumbnail_url or item.thumbnail_url,
         )
+        if save_content:
+            assert page_data.saved_content
+            assert page_data.format_info
+            content_item = url_item.new_copy_with(
+                external_path=str(page_data.saved_content),
+                # Use the original filename, not the local cache filename (which has a hash suffix).
+                original_filename=item.get_filename(),
+                format=page_data.format_info.format,
+            )
+            ws.save(content_item)
 
-    if not fetched_item.title:
+    if not url_item.title:
         log.warning("Failed to fetch page data: title is missing: %s", item.url)
 
-    ws.save(fetched_item)
+    # Now save the updated URL item and also the content item if we have one.
+    ws.save(url_item)
+    assert url_item.store_path
+    log.debug("Saved URL item: %s", url_item.fmt_loc())
+    if content_item:
+        ws.save(content_item)
+        assert content_item.store_path
+        log.debug("Saved content item: %s", content_item.fmt_loc())
 
-    return fetched_item
+    return content_item or url_item

{kash_shell-0.3.18 → kash_shell-0.3.20}/src/kash/file_storage/file_store.py

@@ -405,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)
@@ -480,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: %s", EMOJI_SAVED, 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_shell-0.3.18 → kash_shell-0.3.20}/src/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_shell-0.3.18 → kash_shell-0.3.20}/src/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_shell-0.3.18 → kash_shell-0.3.20}/src/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_shell-0.3.18 → kash_shell-0.3.20}/src/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_shell-0.3.18 → kash_shell-0.3.20}/src/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())