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

kash/web_content/local_file_cache.py

@@ -11,7 +11,7 @@ from prettyfmt import fmt_path
 from strif import atomic_output_file, copyfile_atomic
 
 from kash.utils.common.url import Url, is_file_url, is_url, normalize_url, parse_file_url
-from kash.utils.errors import FileNotFound, InvalidInput
+from kash.utils.errors import FileNotFound
 from kash.utils.file_utils.file_formats_model import choose_file_ext
 from kash.web_content.dir_store import DirStore
 from kash.web_content.web_fetch import download_url
@@ -56,19 +56,21 @@ class Loadable:
 
     key: str
     """
-    The unique identifier for the item. If it ends in a recognized file extension,
-    both the key and the extension will be used when creating unique cache filenames.
+    The unique identifier for the item. Used when creating unique cache filenames,
+    as is or with added suffixes.
     """
 
     save: Callable[[Path], None]
     """
     Method that saves the item to the given path. Caller will handle path selection
-    and atomicity of file creation.
+    and atomicity of file creation. Raise an exception if the item cannot be saved.
     """
 
 
 Cacheable = Url | Path | Loadable
-"""An item that can be cached as a file."""
+"""
+An item that can be cached as a file.
+"""
 
 
 def _suffix_for(cacheable: Cacheable) -> str | None:
@@ -151,9 +153,7 @@ class LocalFileCache(DirStore):
             if isinstance(url_or_path, Path):
                 file_path = url_or_path
             else:
-                parsed = parse_file_url(url_or_path)
-                if not parsed:
-                    raise InvalidInput(f"Not a file URL: {url_or_path}")
+                parsed = parse_file_url(url_or_path)  # Raises ValueError if not a file URL.
                 file_path = parsed
             if not file_path.exists():
                 raise FileNotFound(f"File not found: {file_path}")
@@ -173,7 +173,10 @@ class LocalFileCache(DirStore):
             ) as tmp_path:
                 source.save(tmp_path)
             if not cache_path.exists():
-                raise InvalidCacheState(f"Failed to save to cache: {source}: {cache_path}")
+                # The source should have raised an exception if it failed to save.
+                raise InvalidCacheState(
+                    f"Loadable source failed to save to cache: {source}: {cache_path}"
+                )
         else:
             raise ValueError(f"Invalid source: {source}")
 

kash/web_content/web_extract.py

@@ -10,14 +10,19 @@ from kash.web_content.web_page_model import PageExtractor, WebPageData
 
 @log_calls(level="message")
 def fetch_extract(
-    url: Url, use_cache: bool = True, extractor: PageExtractor = extract_text_justext
+    url: Url,
+    refetch: bool = False,
+    use_cache: bool = True,
+    extractor: PageExtractor = extract_text_justext,
 ) -> WebPageData:
     """
     Fetches a URL and extracts the title, description, and content.
+    By default, uses the content cache if available. Can force re-fetching and
+    updating the cache by setting `refetch` to true.
     """
-
+    expiration_sec = 0 if refetch else None
     if use_cache:
-        path, _was_cached = cache_file(url)
+        path, _was_cached = cache_file(url, expiration_sec=expiration_sec)
         with open(path, "rb") as file:
             content = file.read()
         page_data = extractor(url, content)

kash/web_content/web_fetch.py

@@ -7,17 +7,22 @@ import httpx
 from strif import atomic_output_file, copyfile_atomic
 from tqdm import tqdm
 
+from kash.config.env_settings import KashEnv
 from kash.utils.common.url import Url
 
 log = logging.getLogger(__name__)
 
-USER_AGENT = "Mozilla/5.0 (Compatible)"
 
 DEFAULT_TIMEOUT = 30
 
 
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:126.0) Gecko/20100101 Firefox/126.0"
+)
+
+
 def default_headers() -> dict[str, str]:
-    return {"User-Agent": USER_AGENT}
+    return {"User-Agent": KashEnv.KASH_USER_AGENT.read_str(default=DEFAULT_USER_AGENT)}
 
 
 def fetch_url(
@@ -36,6 +41,7 @@ def fetch_url(
         auth=auth,
         headers=headers or default_headers(),
     ) as client:
+        log.debug("fetch_url: using headers: %s", client.headers)
         response = client.get(url)
         log.info("Fetched: %s (%s bytes): %s", response.status_code, len(response.content), url)
         response.raise_for_status()
@@ -52,7 +58,7 @@ def download_url(
     headers: dict[str, str] | None = None,
 ) -> None:
     """
-    Download given file, optionally with progress bar.
+    Download given file, optionally with progress bar, streaming to a target file.
     Also handles file:// and s3:// URLs. Output file is created atomically.
     Raise httpx.HTTPError for non-2xx responses.
     """
@@ -73,13 +79,15 @@ def download_url(
         client = session or httpx.Client(follow_redirects=True, timeout=timeout)
         response: httpx.Response | None = None
         try:
+            headers = headers or default_headers()
+            log.debug("download_url: using headers: %s", headers)
             with client.stream(
                 "GET",
                 url,
                 follow_redirects=True,
                 timeout=timeout,
                 auth=auth,
-                headers=headers or default_headers(),
+                headers=headers,
             ) as response:
                 response.raise_for_status()
                 total_size = int(response.headers.get("content-length", "0"))

kash/web_gen/tabbed_webpage.py

@@ -2,6 +2,7 @@ import os
 from dataclasses import asdict, dataclass
 
 from frontmatter_format import read_yaml_file, to_yaml_string, write_yaml_file
+from prettyfmt import sanitize_title
 
 from kash.config.logger import get_logger
 from kash.exec.preconditions import has_thumbnail_url
@@ -41,7 +42,7 @@ def _fill_in_ids(tabs: list[TabInfo]):
             tab.id = f"tab_{i}"
 
 
-def webpage_config(items: list[Item]) -> Item:
+def webpage_config(items: list[Item], clean_headings: bool = False) -> Item:
     """
     Get an item with the config for a tabbed web page.
     """
@@ -57,9 +58,11 @@ def webpage_config(items: list[Item]) -> Item:
             log.warning("Item has no thumbnail URL: %s", item)
             return None
 
+    clean = clean_heading if clean_headings else sanitize_title
+
     tabs = [
         TabInfo(
-            label=clean_heading(item.abbrev_title()),
+            label=clean(item.abbrev_title()),
             store_path=item.store_path,
             thumbnail_url=get_thumbnail_url(item),
         )

kash/web_gen/templates/base_styles.css.jinja

@@ -1,8 +1,9 @@
 :root {
   font-size: 16px;
-  {# Adding Hack Nerd Font to all fonts for icon support, if it is installed. #}
-  --font-sans: "Varta", sans-serif, "Hack Nerd Font";
+  /* Adding Hack Nerd Font to all fonts for icon support, if it is installed. */
+  --font-sans: "Source Sans 3 Variable", sans-serif, "Hack Nerd Font";
   --font-serif: "PT Serif", serif, "Hack Nerd Font";
+  --font-weight-sans-bold: 625;  /* Source Sans 3 Variable better at this weight. */
   --font-mono: "Hack Nerd Font", "Menlo", "DejaVu Sans Mono", Consolas, "Lucida Console", monospace;
 
   --font-size-large: 1.2rem;
@@ -63,16 +64,32 @@
 body {
   font-family: var(--font-serif);
   color: var(--color-text);
-  line-height: 1.3;
+  line-height: 1.4;
   padding: 0;  /* No padding so we can have full width elements. */
   margin: auto;
   background-color: var(--color-bg);
+  overflow-wrap: break-word;  /* Don't let long words/URLs break layout. */
 }
 
 p {
   margin-bottom: 1rem;
 }
 
+b, strong {
+  font-weight: var(--font-weight-sans-bold);
+}
+
+a {
+  color: var(--color-primary);
+  text-decoration: none;
+}
+
+a:hover {
+  color: var(--color-primary-light);
+  text-decoration: underline;
+  transition: all 0.15s ease-in-out;
+}
+
 h1,
 h2,
 h3,
@@ -88,19 +105,19 @@ h1 {
 
 h2 {
   font-size: 1.4rem;
-  margin-top: 2rem;
+  margin-top: 2.5rem;
   margin-bottom: 1rem;
 }
 
 h3 {
-  font-size: 1.15rem;
-  margin-top: 1.5rem;
-  margin-bottom: 1rem;
+  font-size: 1.09rem;
+  margin-top: 1.7rem;
+  margin-bottom: 0.7rem;
 }
 
 h4 {
   margin-top: 1rem;
-  margin-bottom: 1rem;
+  margin-bottom: 0.7rem;
 }
 
 /* Long text stylings, for nicely formatting blog post length or longer texts. */
@@ -118,8 +135,9 @@ h4 {
 
 .long-text h3 {
   font-family: var(--font-sans);
-  font-weight: 700;
+  font-weight: var(--font-weight-sans-bold);
   text-transform: uppercase;
+  letter-spacing: 0.02em;
 }
 
 .long-text h4 {
@@ -141,22 +159,31 @@ ul {
 }
 
 li {
-  margin-top: 0.5rem;
+  margin-top: 0.7rem;
   margin-bottom: 0;
   position: relative;
 }
 
-ul>li::before {
+li > p {
+  margin-bottom: 0;
+}
+
+ul > li::before {
   content: "▪︎";
   position: absolute;
-  left: -1rem;
-  font-size: 0.9rem;
+  left: -.85rem;
+  top: .25rem;
+  font-size: 0.62rem;
 }
 
 ol {
+  margin-bottom: 0.7rem;
   list-style-type: decimal;
   margin-left: 2rem;
-  margin-bottom: 1rem;
+}
+
+ol > li {
+  padding-left: 0.25rem;
 }
 
 blockquote {
@@ -181,6 +208,37 @@ pre {
   {# overflow-x: auto; #}
 }
 
+table {
+  font-family: var(--font-sans);
+  font-size: var(--font-size-small);
+  width: auto;
+  margin-left: auto;
+  margin-right: auto;
+  border-collapse: collapse;
+  word-break: break-word; /* long words/URLs wrap instead of inflating the column    */
+  border: 1px solid var(--color-border-hint);
+}
+
+th {
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+  border-bottom: 1px solid var(--color-border-hint);
+}
+
+th, td {
+  padding: 0.3rem 0.6rem;
+  max-width: 40rem;
+  min-width: 6rem;
+}
+
+th {
+  background-color: var(--color-bg-alt-solid);
+}
+
+tbody tr:nth-child(even) {
+  background-color: var(--color-bg-alt-solid); 
+}
+
 nav {
   display: flex;
   flex-wrap: wrap;
@@ -190,3 +248,51 @@ nav {
   gap: 1rem;
   /* Add some space between the buttons */
 }
+
+/* Container for wide tables to allow tables to break out of parent width. */
+.table-container {
+  {# max-width: calc(100vw - 6rem); #}
+  position: relative;
+  left: 50%;
+  transform: translateX(-50%);
+  box-sizing: border-box;
+  margin-bottom: 1rem;
+  background-color: var(--color-bg-solid);
+
+}
+
+/* Bleed wide on larger screens. */
+/* TODO: Don't make so wide if table itself isn't large? */
+@media (min-width: 768px) {
+  table {
+    width: calc(100vw - 6rem);
+  }
+  .table-container {
+    width: calc(100vw - 6rem);
+  }
+}
+
+@media (max-width: 768px) {
+  table {
+    font-size: var(--font-size-smaller);
+  }
+}
+
+/* Footnotes. */
+sup {
+  font-size: 80%;
+}
+
+.footnote-ref a, .footnote {
+  text-decoration: none;
+  padding: 0 0.15rem;
+  border-radius: 4px;
+  transition: all 0.15s ease-in-out;
+}
+
+.footnote-ref a:hover, .footnote:hover {
+  background-color: var(--color-hover-bg);
+  color: var(--color-primary-light);
+  text-decoration: none;
+}
+

kash/web_gen/templates/base_webpage.html.jinja

@@ -20,12 +20,19 @@
   <link rel="preload" as="font" type="font/woff2" crossorigin
     href="https://cdn.jsdelivr.net/fontsource/fonts/pt-serif@latest/latin-700-italic.woff2" />
   <link rel="preload" as="font" type="font/woff2" crossorigin
-    href="https://cdn.jsdelivr.net/fontsource/fonts/varta:vf@latest/latin-wght-normal.woff2" />
+    href="https://cdn.jsdelivr.net/fontsource/fonts/source-sans-3:vf@latest/latin-wght-normal.woff2" />
+  <link rel="preload" as="font" type="font/woff2" crossorigin
+    href="https://cdn.jsdelivr.net/fontsource/fonts/source-sans-3:vf@latest/latin-wght-italic.woff2" />
 
   <link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet" />
   <script src="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js" defer></script>
 
+  {% if extra_head %}
+  {{ extra_head|safe }}
+  {% endif %}
+
   <style>
+    /* https://fontsource.org/fonts/pt-serif/cdn */
     /* pt-serif-latin-400-normal */
     @font-face {
       font-family: 'PT Serif';
@@ -62,14 +69,27 @@
       src: url(https://cdn.jsdelivr.net/fontsource/fonts/pt-serif@latest/latin-700-italic.woff2) format('woff2');
       unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
     }
+    /* https://fontsource.org/fonts/source-sans-3/cdn */
+    /* source-sans-3-latin-wght-normal */
     @font-face {
-      font-family: 'Varta';
+      font-family: 'Source Sans 3 Variable';
       font-style: normal;
       font-display: block;
-      font-weight: 300 700;
-      src: url(https://cdn.jsdelivr.net/fontsource/fonts/varta:vf@latest/latin-wght-normal.woff2) format('woff2-variations');
-      unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+      font-weight: 200 900;
+      src: url(https://cdn.jsdelivr.net/fontsource/fonts/source-sans-3:vf@latest/latin-wght-normal.woff2) format('woff2-variations');
+      unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
     }
+    /* source-sans-3-latin-wght-normal */
+    @font-face {
+      font-family: 'Source Sans 3 Variable';
+      font-style: italic;
+      font-display: block;
+      font-weight: 200 900;
+      src: url(https://cdn.jsdelivr.net/fontsource/fonts/source-sans-3:vf@latest/latin-wght-italic.woff2) format('woff2-variations');
+      unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+    }
+
+    {# Other decent sans serif options: Work Sans Variable, Nunito Sans Variable #}
 
     {% include "base_styles.css.jinja" %}
     {% include "content_styles.css.jinja" %}
@@ -82,24 +102,45 @@
 </head>
 
 <body>
-  {{ content|safe }}
-</body>
+{{ content|safe }}
 
 <script>
-  // Some messages are sent to the parent window, in case we are in a viewport like a
-  // tooltip that supports it.
-
-  // Request a resize of the parent viewport (e.g. tooltip).
   document.addEventListener('DOMContentLoaded', () => {
+    // Send messages to the parent window, in case we are in a viewport where that matters
+    // (e.g. an iframe tooltip).
+    // Request a resize of the parent viewport. This iframe size message format isn't
+    // standardized by ResizeObserver, but is common. It is supported by Kerm.
     const content = document.body;
     console.log("Suggesting resize to parent:", content.offsetWidth, content.offsetHeight);
-    // This iframe size message format isn't standardized by ResizeObserver, but is common.
-    // It is supported by Kerm.
+
     window.parent.postMessage({
       type: 'resize',
       width: Math.max(content.offsetWidth, 600),
       height: Math.max(content.offsetHeight, 100)
     }, '*');
+
+    // Wrap tables within the main content area for horizontal scrolling.
+    const containers = [];
+    document.querySelectorAll('.long-text').forEach(el => {
+      const pane = el.querySelector('.tab-pane');
+      containers.push(pane || el);
+    });
+    containers.forEach(container => {
+      // Grab all tables, then only wrap the ones whose parent is this container.
+      container.querySelectorAll('table').forEach(table => {
+        if (table.parentElement !== container) {
+          return; // Only direct children.
+        }
+        if (table.parentNode.classList.contains('table-container')) {
+          return; // Already wrapped.
+        }
+        const wrapper = document.createElement('div');
+        wrapper.className = 'table-container';
+        container.insertBefore(wrapper, table);
+        wrapper.appendChild(table);
+      });
+    });
+
   });
 
   // Double-click to expand (e.g. expand tooltip to popover).
@@ -119,6 +160,12 @@
       }, '*');
     }
   });
+
+  {% if extra_footer_js %}
+  {{ extra_footer_js|safe }}
+  {% endif %}
 </script>
 
+</body>
+
 </html>

kash/web_gen/templates/content_styles.css.jinja

@@ -15,7 +15,7 @@
   padding: 0 0.4rem;
 }
 
-/* More novel bracket ideas: [❲⟦⟪⟬〔〘〚〖 ]❳⟧⟫⟭ 〕〙〛〗 */
+{# More novel bracket ideas: [❲⟦⟪⟬〔〘〚〖 ]❳⟧⟫⟭ 〕〙〛〗 #}
 .citation::before {
   content: "[";
 }
@@ -57,6 +57,7 @@
   font-weight: 500;
   font-size: 1.2rem;
   text-transform: uppercase;
+  letter-spacing: 0.02em;
   margin-bottom: 0.5rem;
 }
 
@@ -81,6 +82,7 @@
   font-weight: 500;
   font-size: 1.2rem;
   text-transform: uppercase;
+  letter-spacing: 0.02em;
   margin-bottom: 0.5rem;
 
   /* Hack to center the header above the columns */
@@ -107,7 +109,7 @@
   font-size: var(--font-size-small);
   font-weight: 600;
   text-transform: uppercase;
-  letter-spacing: 0.05em;
+  letter-spacing: 0.02em;
   line-height: 1.2;
   padding: 0 0.5rem;
   border-bottom-width: 2px;

kash/web_gen/templates/item_view.html.jinja

@@ -19,9 +19,9 @@
 .item-type {
   font-family: var(--font-sans);
   text-transform: uppercase;
+  letter-spacing: 0.02em;
   font-size: var(--font-size-smaller);
-  font-weight: 800;
-  letter-spacing: 0.05em;
+  font-weight: var(--font-weight-sans-bold);
   padding-right: 1rem;
 }
 

kash/web_gen/templates/tabbed_webpage.html.jinja

@@ -1,4 +1,4 @@
-<div class="long-text container max-w-3xl mx-auto bg-white py-8 px-16 shadow-lg">
+<div class="long-text container max-w-3xl mx-auto bg-white py-8 px-6 md:px-16 md:shadow-lg">
   <h1 class="text-center text-4xl mt-6 mb-6">{{ title }}</h1>
   <div>
     <!-- Navigation Tabs -->
@@ -30,7 +30,6 @@
       {% endfor %}
     </div>
   </div>
-  <!-- TODO: Footer info (match with pdf export) -->
 </div>
 
 <script>

kash/workspaces/__init__.py

@@ -1,5 +1,3 @@
-# flake8: noqa: F401
-
 from kash.workspaces.selections import Selection, SelectionHistory
 from kash.workspaces.workspaces import (
     Workspace,
@@ -9,5 +7,20 @@ from kash.workspaces.workspaces import (
     get_ws,
     global_ws_dir,
     resolve_ws,
+    switch_to_ws,
     ws_param_value,
 )
+
+__all__ = [
+    "Selection",
+    "SelectionHistory",
+    "Workspace",
+    "current_ignore",
+    "current_ws",
+    "get_global_ws",
+    "get_ws",
+    "global_ws_dir",
+    "resolve_ws",
+    "ws_param_value",
+    "switch_to_ws",
+]

kash/workspaces/selections.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from collections.abc import Callable, Sequence
 from functools import wraps
 from pathlib import Path
@@ -78,6 +80,12 @@ class Selection(BaseModel):
                 if current_path == old_path:
                     self.paths[idx] = new_path
 
+    def refresh(self, base_dir: Path) -> None:
+        """
+        Refresh the selection paths, dropping any that no longer exist.
+        """
+        self.paths[:] = [p for p in self.paths if (base_dir / p).exists()]
+
     def as_str(self, max_lines: int = SELECTION_DISPLAY_MAX) -> str:
         lines = [
             f"{fmt_count_items(len(self.paths), 'item')}:",
@@ -113,7 +121,7 @@ class SelectionHistory(BaseModel):
     }
 
     @classmethod
-    def init(cls, save_path: Path, max_history: int = SELECTION_HISTORY_MAX) -> "SelectionHistory":
+    def init(cls, save_path: Path, max_history: int = SELECTION_HISTORY_MAX) -> SelectionHistory:
         """
         Initialize selection history, loading from save_path if it exists.
         """
@@ -144,9 +152,9 @@ class SelectionHistory(BaseModel):
         yaml_util.write_yaml_file(data, str(self._save_path))
 
     @persist_after(_save)
-    def clear(self) -> None:
+    def clear_all(self) -> None:
         """
-        Clear the history.
+        Clear the entire selection history.
         """
         self.history.clear()
         self.current_index = 0
@@ -306,6 +314,13 @@ class SelectionHistory(BaseModel):
         for selection in self.history:
             selection.replace_values(replacements)
 
+    @persist_after(_save)
+    def refresh_current(self, base_dir: Path) -> None:
+        """
+        Refresh the current selection to drop any paths that no longer exist.
+        """
+        self.current.refresh(base_dir)
+
     def previous_n(self, n: int, expected_size: int | None = None) -> list[Selection]:
         """
         Get the `n` previous selections (backwards and including the current position),

kash/workspaces/source_items.py

@@ -7,7 +7,6 @@ from kash.model.items_model import Item
 from kash.model.paths_model import StorePath
 from kash.model.preconditions_model import Precondition
 from kash.utils.common.format_utils import fmt_loc
-from kash.utils.common.type_utils import not_none
 from kash.utils.errors import NoMatch
 from kash.workspaces import current_ws