Can create, edit, and delete an alias in the UI

Author: davidfstr

RELEASE_NOTES.md

@@ -12,6 +12,15 @@ Release Notes ⋮
 
 ### main
 
+* Workflow improvements
+    * Aliases are now supported for redirecting similar patterns of URLs,
+      such as `https://www.folklore.org/ → https://folklore.org/`.
+        * Use the "New Alias..." menuitem in the "Entity" menu to create an Alias.
+    * Aliases can be used to redirect to external URLs outside the project,
+      on the live internet.
+        * This can be useful if a subset of a project's URLs are hosted in
+          a different internet-accessible subsystem, such as AWS Glacier.
+
 * Shell improvements
     * Uses the new [interactive interpreter] from Python 3.13.
     * Supports using `await` with Crystal's testing utilities

src/crystal/browser/__init__.py

@@ -6,12 +6,13 @@
 from crystal.app_preferences import app_prefs
 from crystal.browser.entitytree import EntityTree
 from crystal.browser.icons import TREE_NODE_ICONS
+from crystal.browser.new_alias import NewAliasDialog
 from crystal.browser.new_group import NewGroupDialog
 from crystal.browser.new_root_url import ChangePrefixCommand, NewRootUrlDialog
 from crystal.browser.preferences import PreferencesDialog
 from crystal.browser.tasktree import TaskTree, TaskTreeNode
 from crystal.model import (
-    Project, ProjectReadOnlyError, Resource, ResourceGroup, ResourceGroupSource, RootResource,
+    Alias, Project, ProjectReadOnlyError, Resource, ResourceGroup, ResourceGroupSource, RootResource,
 )
 from crystal.progress import (
     CancelLoadUrls, CancelSaveAs, DummyOpenProjectProgressListener,
@@ -316,6 +317,11 @@ def _create_actions(self) -> None:
             enabled=(not self._readonly),
             button_bitmap=dict(DEFAULT_FOLDER_ICON_SET())[wx.TreeItemIcon_Normal],
             button_label='New &Group...')
+        self._new_alias_action = Action(wx.ID_ANY,
+            'New &Alias...',
+            wx.AcceleratorEntry(wx.ACCEL_CTRL | wx.ACCEL_SHIFT, ord('A')),
+            self._on_new_alias,
+            enabled=(not self._readonly))
         self._edit_action = Action(wx.ID_ANY,
             self._EDIT_ACTION_LABEL if not self._readonly else self._GET_INFO_ACTION_LABEL,
             accel=wx.AcceleratorEntry(wx.ACCEL_NORMAL, wx.WXK_RETURN),
@@ -438,6 +444,7 @@ def _create_menu_bar(self, raw_frame: wx.Frame) -> wx.MenuBar:
         entity_menu.AppendSeparator()
         self._new_root_url_action.append_menuitem_to(entity_menu)
         self._new_group_action.append_menuitem_to(entity_menu)
+        self._new_alias_action.append_menuitem_to(entity_menu)
         self._edit_action.append_menuitem_to(entity_menu)
         self._forget_action.append_menuitem_to(entity_menu)
         entity_menu.AppendSeparator()
@@ -815,7 +822,8 @@ def _update_entity_pane_empty_state_visibility(self) -> bool:
         """
         is_project_empty = (
             is_iterable_empty(self.project.root_resources) and
-            is_iterable_empty(self.project.resource_groups)
+            is_iterable_empty(self.project.resource_groups) and
+            is_iterable_empty(self.project.aliases)
         )
 
         sizer_index = self._entity_tree_sizer_index  # cache
@@ -1412,16 +1420,56 @@ def _on_edit_group_dialog_ok(self,
 
         assert download_immediately == False
 
-    def _saving_source_would_create_cycle(self, rg: ResourceGroup, source: ResourceGroupSource) -> bool:
-        ancestor_source = source  # type: ResourceGroupSource
-        while ancestor_source is not None:
-            if ancestor_source == rg:
-                return True
-            if isinstance(ancestor_source, ResourceGroup):
-                ancestor_source = ancestor_source.source  # reinterpret
-            else:
-                ancestor_source = None
-        return False
+    # === Entity Pane: New/Edit Alias ===
+    
+    def _on_new_alias(self, event: wx.CommandEvent) -> None:
+        restore_menuitems = self._disable_menus_during_showwindowmodal()
+        NewAliasDialog(
+            self._frame,
+            self._on_new_alias_dialog_ok,
+            alias_exists_func=self._alias_exists,
+            on_close=restore_menuitems,
+        )
+    
+    def _alias_exists(self, source_url_prefix: str) -> bool:
+        return self.project.get_alias(source_url_prefix) is not None
+    
+    @fg_affinity
+    def _on_new_alias_dialog_ok(self,
+            source_url_prefix: str,
+            target_url_prefix: str,
+            target_is_external: bool,
+            ) -> None:
+        if source_url_prefix == '':
+            raise ValueError('Invalid blank source URL prefix')
+        if target_url_prefix == '':
+            raise ValueError('Invalid blank target URL prefix')
+        
+        try:
+            alias = Alias(self.project, source_url_prefix, target_url_prefix,
+                         target_is_external=target_is_external)
+        except Alias.AlreadyExists:
+            raise ValueError('Invalid duplicate source URL prefix')
+    
+    @fg_affinity
+    def _on_edit_alias_dialog_ok(self,
+            alias: Alias,
+            source_url_prefix: str,
+            target_url_prefix: str,
+            target_is_external: bool,
+            ) -> None:
+        if source_url_prefix != alias.source_url_prefix:
+            raise ValueError(
+                'Attempted to change source_url_prefix of existing Alias. '
+                'Source URL prefix cannot be changed after alias is created.'
+            )
+        
+        if target_url_prefix == '':
+            raise ValueError('Invalid blank target URL prefix')
+        
+        # NOTE: Entity tree update will be triggered by property setters
+        alias.target_url_prefix = target_url_prefix
+        alias.target_is_external = target_is_external
 
     # === Entity Pane: Other Commands ===
 
@@ -1486,9 +1534,38 @@ def _on_edit_entity(self, event) -> None:
                     raise
             except CancelLoadUrls:
                 pass
+        elif isinstance(selected_entity, Alias):
+            alias = selected_entity
+            restore_menuitems = self._disable_menus_during_showwindowmodal()
+            try:
+                NewAliasDialog(
+                    self._frame,
+                    partial(self._on_edit_alias_dialog_ok, alias),
+                    alias_exists_func=self._alias_exists,
+                    initial_source_url_prefix=alias.source_url_prefix,
+                    initial_target_url_prefix=alias.target_url_prefix,
+                    initial_target_is_external=alias.target_is_external,
+                    is_edit=True,
+                    readonly=self._readonly,
+                    on_close=restore_menuitems,
+                )
+            except:
+                restore_menuitems()
+                raise
         else:
             raise AssertionError()
 
+    def _saving_source_would_create_cycle(self, rg: ResourceGroup, source: ResourceGroupSource) -> bool:
+        ancestor_source = source  # type: ResourceGroupSource
+        while ancestor_source is not None:
+            if ancestor_source == rg:
+                return True
+            if isinstance(ancestor_source, ResourceGroup):
+                ancestor_source = ancestor_source.source  # reinterpret
+            else:
+                ancestor_source = None
+        return False
+    
     def _on_forget_entity(self, event) -> None:
         selected_entity = self.entity_tree.selected_entity
         assert selected_entity is not None
@@ -1498,6 +1575,7 @@ def _on_forget_entity(self, event) -> None:
     def _on_download_entity(self, event) -> None:
         selected_entity = self.entity_tree.selected_entity
         assert selected_entity is not None
+        assert not isinstance(selected_entity, Alias)
 
         # Show progress dialog in advance if will need to load all project URLs
         if isinstance(selected_entity, ResourceGroup):
@@ -1612,21 +1690,33 @@ def resource_group_did_instantiate(self, group: ResourceGroup) -> None:
     def resource_group_did_forget(self, group: ResourceGroup) -> None:
         self._update_entity_pane_empty_state_visibility()
 
+    # NOTE: Can't capture to the Entity Tree itself reliably since may not be visible
+    @capture_crashes_to_stderr
+    @cloak
+    def alias_did_instantiate(self, alias: Alias) -> None:
+        self._update_entity_pane_empty_state_visibility()
+    
+    # NOTE: Can't capture to the Entity Tree itself reliably since may not be visible
+    @capture_crashes_to_stderr
+    @cloak
+    def alias_did_forget(self, alias: Alias) -> None:
+        self._update_entity_pane_empty_state_visibility()
+    
     def _on_selected_entity_changed(self, event: wx.TreeEvent | None=None) -> None:
         selected_entity = self.entity_tree.selected_entity  # cache
 
         readonly = self._readonly  # cache
         self._edit_action.enabled = (
-            isinstance(selected_entity, (ResourceGroup, RootResource)))
+            isinstance(selected_entity, (Alias, ResourceGroup, RootResource)))
         self._forget_action.enabled = (
             (not readonly) and
-            isinstance(selected_entity, (ResourceGroup, RootResource)))
+            isinstance(selected_entity, (Alias, ResourceGroup, RootResource)))
         self._update_members_action.enabled = (
             (not readonly) and
             isinstance(selected_entity, ResourceGroup))
         self._download_action.enabled = (
             (not readonly) and
-            selected_entity is not None)
+            isinstance(selected_entity, (Resource, ResourceGroup, RootResource)))
         self._view_action.enabled = (
             isinstance(selected_entity, (Resource, RootResource)))
 

src/crystal/browser/entitytree.py

@@ -7,7 +7,7 @@
 from crystal.doc.generic import Link
 from crystal.doc.html.soup import TEXT_LINK_TYPE_TITLE
 from crystal.model import (
-    Project, ProjectHasTooManyRevisionsError, Resource, ResourceGroup,
+    Alias, Project, ProjectHasTooManyRevisionsError, Resource, ResourceGroup,
     ResourceGroupSource, ResourceRevision, RevisionBodyMissingError,
     RevisionDeletedError, RootResource,
 )
@@ -306,6 +306,39 @@ def resource_group_did_forget(self, group: ResourceGroup) -> None:
         # may need to be updated
         self.root.update_icon_set_of_descendants_in_group(group)
 
+    # === Events: Alias Lifecycle ===
+    
+    @capture_crashes_to_self
+    def alias_did_instantiate(self, alias: Alias) -> None:
+        selection_was_empty = self.view.selected_node in [None, self.view.root]  # capture
+        
+        self.update()
+        
+        if selection_was_empty:
+            # Select the newly-created entity
+            for child in self.root.children:
+                if child.entity == alias:
+                    child.view.peer.SelectItem()
+                    break
+    
+    @capture_crashes_to_self
+    # TODO: Do not recommend asserting that a listener method will be called
+    #       from any particular thread
+    @fg_affinity
+    def alias_did_change(self, alias: Alias) -> None:
+        # Update the title of the AliasNode
+        for child in self.root.children:
+            if isinstance(child, AliasNode) and child.alias == alias:
+                child.view.title = child.calculate_title()
+                break
+    
+    @capture_crashes_to_self
+    # TODO: Do not recommend asserting that a listener method will be called
+    #       from any particular thread
+    @fg_affinity
+    def alias_did_forget(self, alias: Alias) -> None:
+        self.update()
+    
     # === Event: Min Fetch Date Did Change ===
 
     @capture_crashes_to_self
@@ -524,7 +557,7 @@ def _sequence_with_matching_elements_replaced(new_seq, old_seq):
     return [old_seq_selfdict.get(x, x) for x in new_seq]
 
 
-NodeEntity: TypeAlias = Union['RootResource', 'Resource', 'ResourceGroup']
+NodeEntity: TypeAlias = Union['RootResource', 'Resource', 'ResourceGroup', 'Alias']
 
 
 class Node(Bulkhead):
@@ -771,6 +804,9 @@ def update_children(self,
         for (index, rg) in enumerate(self._project.resource_groups):
             children.append(ResourceGroupNode(rg))
 
+        for alias in self._project.aliases:
+            children.append(AliasNode(alias))
+        
         self.set_children(children, progress_listener)
 
 
@@ -1013,7 +1049,7 @@ def update_children(self) -> None:
         if self.resource_links:
             for link in self.resource_links:
                 url = urljoin(self.resource.url, link.relative_url)
-                resource = Resource(self._project, url)
+                resource = Resource(self._project, url, _external_ok=True)
                 resources_2_links[resource].append(link)
 
         linked_root_resources = []
@@ -1556,6 +1592,80 @@ def __hash__(self) -> int:
         return hash(self.resource_group)
 
 
+class AliasNode(Node):
+    """Node representing an Alias in the entity tree."""
+    entity_tooltip = 'alias'
+    
+    ICON = '🔗'
+    ICON_TRUNCATION_FIX = '' 
+    
+    def __init__(self, alias: Alias) -> None:
+        super().__init__(source=None)
+        self.alias = alias
+        
+        self.view = NodeView()
+        # NOTE: Defer expensive calculation until if/when the icon_set is used
+        self.view.icon_set = self.calculate_icon_set
+        self.view.title = self.calculate_title()
+        self.view.expandable = False
+        
+        # Aliases have no children
+        self.children = []
+    
+    # === Properties ===
+    
+    @override
+    def calculate_icon_set(self) -> IconSet | None:
+        return (
+            (wx.TreeItemIcon_Normal, TREE_NODE_ICONS()['entitytree_alias']),
+        )
+    
+    @override
+    @property
+    def icon_tooltip(self) -> str | None:
+        return self.entity_tooltip.capitalize()
+    
+    @override
+    def calculate_title(self) -> str:
+        return self.calculate_title_of(self.alias)
+    
+    @staticmethod
+    def calculate_title_of(alias: Alias) -> str:
+        target_url_prefix = alias.target_url_prefix
+        if alias.target_is_external:
+            target_url_prefix = Alias.format_external_url_for_display(target_url_prefix)
+        assert alias.source_url_prefix.endswith('/')
+        assert target_url_prefix.endswith('/')
+        return f'{alias.source_url_prefix}** → {target_url_prefix}**'
+    
+    @override
+    @property
+    def label_tooltip(self) -> str:
+        tooltip = (
+            f'Source: {self.alias.source_url_prefix}**\n'
+            f'Target: {self.alias.target_url_prefix}**'
+        )
+        if self.alias.target_is_external:
+            tooltip += '\nExternal: Yes (on internet, outside project)'
+        return tooltip
+    
+    @override
+    @property
+    def entity(self) -> Alias:
+        return self.alias
+    
+    # === Comparison ===
+    
+    def __eq__(self, other):
+        return (
+            isinstance(other, AliasNode) and
+            self.alias == other.alias
+        )
+    
+    def __hash__(self):
+        return hash(self.alias)
+
+
 class GroupedLinkedResourcesNode(_GroupedNode):
     entity_tooltip = 'grouped URLs'
 

src/crystal/browser/icons.py

@@ -13,6 +13,7 @@ def TREE_NODE_ICONS() -> dict[str, wx.Bitmap]:
         (icon_name, _load_png_resource(f'treenodeicon_{icon_name}.png'))
         for icon_name in [
             # Entity Tree Icons
+            'entitytree_alias',
             'entitytree_cluster_embedded',
             'entitytree_cluster_offsite',
             'entitytree_loading',