📝 Add docstrings to staging

Docstrings generation was requested by @gmbrax.

* https://github.com/gmbrax/Pilgrim/pull/48#issuecomment-3076555726

The following files were modified:

* `src/pilgrim/ui/screens/diary_list_screen.py`
* `src/pilgrim/ui/screens/edit_diary_modal.py`
* `src/pilgrim/ui/screens/new_diary_modal.py`

pyproject.toml

@@ -5,7 +5,7 @@
 
     [project]
     name = "Pilgrim"
-    version = "0.0.4"
+    version = "0.0.3"
     authors = [
       { name="Gustavo Henrique Santos Souza de Miranda", email="gustavohssmiranda@gmail.com" }
     ]
@@ -20,9 +20,6 @@
     dependencies = [
       "sqlalchemy",
         "textual",
-        "tomli",
-        "tomli_w"
-
 
     ]
     [template.plugins.default]

src/pilgrim/application.py

@@ -1,21 +1,19 @@
 from pilgrim.database import Database
 from pilgrim.service.servicemanager import ServiceManager
 from pilgrim.ui.ui import UIApp
-from pilgrim.utils import ConfigManager
+from pilgrim.utils import DirectoryManager
 
 
 class Application:
     def __init__(self):
-        self.config_manager = ConfigManager()
-        self.config_manager.read_config()  # Chamar antes de criar o Database
-        self.database = Database(self.config_manager)
+        self.config_dir = DirectoryManager.get_config_directory()
+        self.database = Database()
         session = self.database.session()
         session_manager = ServiceManager()
         session_manager.set_session(session)
-        self.ui = UIApp(session_manager, self.config_manager)
+        self.ui = UIApp(session_manager)
 
     def run(self):
-        print(f"URL do banco: {self.config_manager.database_url}")
         self.database.create()
         self.ui.run()
 

src/pilgrim/database.py

@@ -5,24 +5,38 @@ from pathlib import Path
 import os
 import shutil
 
-from pilgrim.utils import ConfigManager
-
 Base = declarative_base()
 
-
+def get_database_path() -> Path:
+    """
+    Get the database file path following XDG Base Directory specification.
+    Creates the directory if it doesn't exist.
+    """
+    # Get home directory
+    home = Path.home()
+    
+    # Create .pilgrim directory if it doesn't exist
+    pilgrim_dir = home / ".pilgrim"
+    pilgrim_dir.mkdir(exist_ok=True)
+    
+    # Database file path
+    db_path = pilgrim_dir / "database.db"
+    
+    # If database doesn't exist in new location but exists in current directory,
+    # migrate it
+    if not db_path.exists():
+        current_db = Path("database.db")
+        if current_db.exists():
+            shutil.copy2(current_db, db_path)
+            print(f"Database migrated from {current_db} to {db_path}")
+    
+    return db_path
 
 class Database:
-
-    def __init__(self, config_manager: ConfigManager):
-        self.db_path = config_manager.database_url
-
-        # Garantir que o diretório existe
-        db_dir = os.path.dirname(self.db_path)
-        if not os.path.exists(db_dir):
-            os.makedirs(db_dir, exist_ok=True)
-
+    def __init__(self):
+        db_path = get_database_path()
         self.engine = create_engine(
-            f"sqlite:///{self.db_path}",
+            f"sqlite:///{db_path}",
             echo=False,
             connect_args={"check_same_thread": False},
         )

src/pilgrim/ui/screens/about_screen.py

@@ -3,7 +3,7 @@ from textual.binding import Binding
 from textual.screen import Screen
 from textual.widgets import Header, Footer, Button, Label, TextArea
 from textual.containers import Container
-from importlib.metadata import version
+
 class AboutScreen(Screen[bool]):
     """Screen to display application information."""
 
@@ -20,7 +20,7 @@ class AboutScreen(Screen[bool]):
         self.app_title = Label("Pilgrim", id="AboutScreen_AboutTitle",classes="AboutScreen_AboutTitle")
         self.content = Label("A TUI Based Travel Diary Application", id="AboutScreen_AboutContent",
                              classes="AboutScreen_AboutContent")
-        self.version = Label(f"Version: {version('Pilgrim')}", id="AboutScreen_AboutVersion",
+        self.version = Label("Version: 0.0.1", id="AboutScreen_AboutVersion",
                              classes="AboutScreen_AboutVersion")
         self.developer = Label("Developed By: Gustavo Henrique Miranda ", id="AboutScreen_AboutAuthor")
         self.contact = Label("git.gustavomiranda.xyz", id="AboutScreen_AboutContact",

src/pilgrim/ui/screens/diary_list_screen.py

@@ -203,11 +203,17 @@ class DiaryListScreen(Screen):
             self.action_open_diary()
 
     def action_new_diary(self):
-        """Action to create new diary"""
+        """
+        Opens the modal dialog to create a new diary and registers a callback for submission.
+        """
         self.app.push_screen(NewDiaryModal(),self._on_new_diary_submitted)
 
     def _on_new_diary_submitted(self, result):
-        """Callback after diary creation"""
+        """
+        Handles the callback after a new diary is submitted.
+        
+        If a diary was created (non-empty result), notifies the user and refreshes the diary list; otherwise, notifies that creation was canceled.
+        """
         if result:  # Se result não é string vazia, o diário foi criado
             self.notify(f"Returning to diary list...")
             # Atualiza a lista de diários
@@ -216,11 +222,17 @@ class DiaryListScreen(Screen):
             self.notify(f"Creation canceled...")
 
     def _on_screen_resume(self) -> None:
-        super()._on_screen_resume()
+        """
+        Refreshes the diary list when the screen resumes.
+        """
         self.refresh_diaries()
 
     def action_edit_selected_diary(self):
-        """Action to edit selected diary"""
+        """
+        Opens the edit dialog for the currently selected diary.
+        
+        If a diary is selected, displays the edit modal and registers a callback for when the edit is submitted. Notifies the user if no diary is selected.
+        """
         if self.selected_diary_index is not None:
             diary_id = self.diary_id_map.get(self.selected_diary_index)
             if diary_id:

src/pilgrim/ui/screens/edit_diary_modal.py

@@ -12,6 +12,9 @@ class EditDiaryModal(ModalScreen[tuple[int,str]]):
     ]
 
     def __init__(self, diary_id: int):
+        """
+        Initialize the EditDiaryModal with the specified diary ID, pre-filling the input field with the current diary name.
+        """
         super().__init__()
         self.diary_id = diary_id
         self.current_diary_name = self.app.service_manager.get_travel_diary_service().read_by_id(self.diary_id).name
@@ -32,16 +35,29 @@ class EditDiaryModal(ModalScreen[tuple[int,str]]):
         self.name_input.cursor_position = len(self.name_input.value)
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
+        """
+        Handle button press events in the modal.
+        
+        Triggers the save action if the "Save" button is pressed, or cancels and dismisses the modal if the "Cancel" button is pressed.
+        """
         if event.button.id == "save_diary_button":
             self.action_edit_diary()
         elif event.button.id == "cancel_button":
             self.dismiss(None)
     def on_key(self, event):
+        """
+        Handles the Enter key press event by triggering the diary save action and preventing the default behavior.
+        """
         if event.key == "enter":
             self.action_edit_diary()
             event.prevent_default()
 
     def action_edit_diary(self) -> None:
+        """
+        Attempts to save the edited diary name, validating input and providing user feedback.
+        
+        If the new name is non-empty and different from the current name, dismisses the modal and returns the diary ID and new name. If the name is unchanged, notifies the user and dismisses without changes. If the input is empty, notifies the user and refocuses the input field.
+        """
         new_diary_name = self.name_input.value.strip()
         if new_diary_name and new_diary_name != self.current_diary_name:
             self.dismiss((self.diary_id, new_diary_name))
@@ -53,8 +69,14 @@ class EditDiaryModal(ModalScreen[tuple[int,str]]):
             self.name_input.focus()
 
     def on_input_submitted(self, event: Input.Submitted) -> None:
+        """
+        Handles submission of the diary name input field by triggering the save action if the relevant input is submitted.
+        """
         if event.input.id == "edit_diary_name_input":
             self.action_edit_diary()
 
     def action_cancel(self) -> None:
+        """
+        Dismisses the modal without saving changes or returning any data.
+        """
         self.dismiss(None)

src/pilgrim/ui/screens/edit_entry_screen.py

@@ -87,7 +87,7 @@ class EditEntryScreen(Screen):
         self.text_entry = TextArea(id="text_entry", classes="EditEntryScreen-text-entry")
 
         # Sidebar widgets
-        self.sidebar_title = Static("Photos", classes="EditEntryScreen-sidebar-title")
+        self.sidebar_title = Static("📸 Photos", classes="EditEntryScreen-sidebar-title")
         self.photo_list = OptionList(id="photo_list", classes="EditEntryScreen-sidebar-photo-list")
         self.photo_info = Static("", classes="EditEntryScreen-sidebar-photo-info")
         self.help_text = Static("", classes="EditEntryScreen-sidebar-help")
@@ -296,28 +296,30 @@ class EditEntryScreen(Screen):
 
             if not self.cached_photos:
                 self.photo_info.update("No photos found for this diary")
-                self.help_text.update("No photos available\n\nUse Photo Manager to add photos")
+                self.help_text.update("📸 No photos available\n\nUse Photo Manager to add photos")
                 return
 
             # Add photos to the list with hash
             for photo in self.cached_photos:
                 # Show name and hash in the list
                 photo_hash = str(photo.photo_hash)[:8]
-                self.photo_list.add_option(f"{photo.name} \\[{photo_hash}\]")
+                self.photo_list.add_option(f"📷 {photo.name} \\[{photo_hash}\]")
 
-            self.photo_info.update(f"{len(self.cached_photos)} photos in diary")
+            self.photo_info.update(f"📸 {len(self.cached_photos)} photos in diary")
 
             # Updated help a text with hash information
             help_text = (
-                "[b]Sidebar Shortcuts[/b]\n"
+                "[b]⌨️  Sidebar Shortcuts[/b]\n"
                 "[b][green]i[/green][/b]: Insert photo into entry\n"
                 "[b][green]n[/green][/b]: Add new photo\n"
                 "[b][green]d[/green][/b]: Delete selected photo\n"
                 "[b][green]e[/green][/b]: Edit selected photo\n"
                 "[b][yellow]Tab[/yellow][/b]: Back to editor\n"
                 "[b][yellow]F8[/yellow][/b]: Show/hide sidebar\n"
+                "[b][yellow]F9[/yellow][/b]: Switch focus (if needed)\n\n"
                 "[b]📝 Photo References[/b]\n"
-                "\\[\\[photo::hash\\]\\]"
+                "Use: \\[\\[photo:name:hash\\]\\]\n"
+                "Or: \\[\\[photo::hash\\]\\]"
             )
             self.help_text.update(help_text)
         except Exception as e:
@@ -427,7 +429,9 @@ class EditEntryScreen(Screen):
         photo_details += f"🔗 {photo_hash}\n"
         photo_details += f"📅 {selected_photo.addition_date}\n"
         photo_details += f"💬 {selected_photo.caption or 'No caption'}\n"
+        photo_details += f"📁 {selected_photo.filepath}\n\n"
         photo_details += f"[b]Reference formats:[/b]\n"
+        photo_details += f"\\[\\[photo:{selected_photo.name}:{photo_hash}\\]\\]\n"
         photo_details += f"\\[\\[photo::{photo_hash}\\]\\]"
 
         self.photo_info.update(photo_details)
@@ -738,15 +742,15 @@ class EditEntryScreen(Screen):
         self.notify(f"Selected photo: {selected_photo.name} \\[{photo_hash}\\]")
 
         # Update photo info with details including hash
-        photo_details = f"Name: {selected_photo.name}\n"
-        photo_details += f"Hash: {photo_hash}\n"
-        photo_details += f"Date: {selected_photo.addition_date}\n"
+        photo_details = f"📷 {selected_photo.name}\n"
+        photo_details += f"🔗 {photo_hash}\n"
+        photo_details += f"📅 {selected_photo.addition_date}\n"
         if selected_photo.caption:
-            photo_details += f"Caption: {selected_photo.caption}\n"
-        else:
-            photo_details += f"Caption: No Caption\n"
+            photo_details += f"💬 {selected_photo.caption}\n"
+        photo_details += f"📁 {selected_photo.filepath}\n\n"
         photo_details += f"[b]Reference formats:[/b]\n"
-        photo_details += f"\\[\\[photo::{photo_hash}]]"
+        photo_details += f"\\[\\[photo:{selected_photo.name}:{photo_hash}\\]\\]\n"
+        photo_details += f"\\[\\[photo::{photo_hash}\\]\\]"
 
         self.photo_info.update(photo_details)
 

src/pilgrim/ui/screens/new_diary_modal.py

@@ -12,13 +12,25 @@ class NewDiaryModal(ModalScreen[str]):
         Binding("escape", "cancel", "Cancel"),
         Binding("enter", "create_diary", "Create",priority=True),
     ]
-    def __init__(self):
+    def __init__(self,autoopen=True):
+        """
+        Initialize the NewDiaryModal with optional automatic opening of the created diary.
+        
+        Parameters:
+            autoopen (bool): If True, the newly created diary will open automatically after creation. Defaults to True.
+        """
         super().__init__()
-        self.auto_open = self.app.config_manager.auto_open_new_diary
+        self.auto_open = autoopen
         self.name_input = Input(id="NewDiaryModal-NameInput",classes="NewDiaryModal-NameInput") # This ID is fine, it's specific to the input
 
     def compose(self) -> ComposeResult:
 
+        """
+        Constructs and yields the UI layout for the new diary modal dialog.
+        
+        Returns:
+            ComposeResult: An iterable of widgets forming the modal, including title, input field, and action buttons.
+        """
         with Vertical(id="new_diary_dialog",classes="NewDiaryModal-Dialog"):
             yield Label("Create a new diary", classes="NewDiaryModal-Title")
             yield Label("Diary Name:")
@@ -33,17 +45,28 @@ class NewDiaryModal(ModalScreen[str]):
           self.name_input.focus()
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
-        """Handles button clicks."""
+        """
+        Handle button press events for the modal.
+        
+        Triggers diary creation when the "Create" button is pressed, or dismisses the modal when the "Cancel" button is pressed.
+        """
         if event.button.id == "create_diary_button":
             self.action_create_diary()
         elif event.button.id == "cancel_button":
             self.dismiss()
 
     def action_cancel(self) -> None:
-        """Action to cancel the modal."""
+        """
+        Cancels the modal dialog and dismisses it without returning a diary name.
+        """
         self.dismiss("")
 
     def action_create_diary(self) -> None:
+        """
+        Validates the diary name input and initiates asynchronous diary creation if valid.
+        
+        If the input is empty, displays a warning notification and refocuses the input field.
+        """
         diary_name = self.name_input.value.strip()
         if diary_name:
 
@@ -54,11 +77,19 @@ class NewDiaryModal(ModalScreen[str]):
             self.name_input.focus()
 
     def on_input_submitted(self, event: Input.Submitted) -> None:
+        """
+        Handles submission of the diary name input field and initiates diary creation if triggered from the correct input.
+        """
         if event.input.id == "NewDiaryModal-NameInput":
             self.action_create_diary()
 
     async def _async_create_diary(self, name: str):
 
+        """
+        Asynchronously creates a new diary entry with the given name and handles post-creation actions.
+        
+        If creation succeeds, dismisses the modal with the diary name, optionally opens the diary for editing, and shows a success notification. If creation fails or an exception occurs, displays an error notification.
+        """
         try:
             service = self.app.service_manager.get_travel_diary_service()
             created_diary = await service.async_create(name)

src/pilgrim/ui/styles/pilgrim.css

@@ -389,10 +389,22 @@ Screen.-modal {
     width: 1fr;
 }
 
-.EditEntryScreen-sidebar{
-    background: $primary-darken-1;
-    width: 45%;
+.EditEntryScreen-sidebar {
+    width: 40;
+    min-height: 10;
+    border-left: solid green;
+    padding: 1;
+    background: $surface-darken-2;
+    color: $primary;
+    text-style: bold;
+    content-align: left top;
 }
+
+.EditEntryScreen-content-container {
+    layout: horizontal;
+    height: 1fr;
+}
+
 .EditEntryScreen-sidebar-title {
     text-align: center;
     text-style: bold;
@@ -405,39 +417,30 @@ Screen.-modal {
 .EditEntryScreen-sidebar-content {
     height: 1fr;
     layout: vertical;
-    margin-left: 1;
-    margin-right: 1;
-
 }
 
 .EditEntryScreen-sidebar-photo-list {
-    height: 2fr; /* Pega o espaço restante disponível */
-    min-height: 5; /* Garante altura mínima para não sumir */
+    height: 1fr;
     border: solid $accent;
     margin-bottom: 1;
-    overflow-y: auto; /* Adiciona scroll vertical se necessário */
 }
 
 .EditEntryScreen-sidebar-photo-info {
-    height: 1fr;
-    max-height: 15; /* Limita altura máxima */
-    min-height: 13;
-    padding: 1;
+    height: auto;
+    min-height: 3;
     border: solid $warning;
+    padding: 1;
     margin-bottom: 1;
     background: $surface-darken-1;
-    overflow-y: auto; /* Adiciona scroll se exceder max-height */
 }
 
 .EditEntryScreen-sidebar-help {
-    height: 1fr;
-    max-height: 10; /* Altura máxima menor que info */
-    min-height: 8; /* Altura mínima menor */
+    height: auto;
+    min-height: 8;
     border: solid $success;
     padding: 1;
     background: $surface-darken-1;
     text-style: italic;
-    overflow-y: auto; /* Adiciona scroll se exceder max-height */
 }
 
 /* Photo Modal Styles */

src/pilgrim/ui/ui.py

@@ -9,7 +9,6 @@ from pilgrim.service.servicemanager import ServiceManager
 from pilgrim.ui.screens.about_screen import AboutScreen
 from pilgrim.ui.screens.diary_list_screen import DiaryListScreen
 from pilgrim.ui.screens.edit_entry_screen import EditEntryScreen
-from pilgrim.utils import ConfigManager
 
 CSS_FILE_PATH = Path(__file__).parent / "styles" / "pilgrim.css"
 
@@ -17,10 +16,9 @@ CSS_FILE_PATH = Path(__file__).parent / "styles" / "pilgrim.css"
 class UIApp(App):
     CSS_PATH = CSS_FILE_PATH
 
-    def __init__(self,service_manager: ServiceManager, config_manager: ConfigManager, **kwargs):
+    def __init__(self,service_manager: ServiceManager, **kwargs):
         super().__init__(**kwargs)
         self.service_manager = service_manager
-        self.config_manager = config_manager
 
 
     def on_mount(self) -> None:

src/pilgrim/utils/__init__.py

@@ -1,4 +1,3 @@
 from .directory_manager import DirectoryManager
-from .config_manager import ConfigManager
 
-__all__ = ['DirectoryManager', 'ConfigManager']
+__all__ = ['DirectoryManager']

src/pilgrim/utils/config_manager.py

@@ -1,107 +0,0 @@
-import os.path
-from os import PathLike
-from threading import Lock
-
-import tomli
-import tomli_w
-
-from pilgrim.utils import DirectoryManager
-
-
-class SingletonMeta(type):
-    _instances = {}
-    _lock: Lock = Lock()
-
-    def __call__(cls, *args, **kwargs):
-        with cls._lock:
-            if cls not in cls._instances:
-                instance = super().__call__(*args, **kwargs)
-                cls._instances[cls] = instance
-        return cls._instances[cls]
-
-
-class ConfigManager(metaclass=SingletonMeta):
-    def __init__(self):
-        self.database_url = None
-        self.database_type = None
-        self.auto_open_diary = None
-        self.auto_open_new_diary = None
-        self.config_dir = DirectoryManager.get_config_directory()
-        self.__data = None
-
-    def read_config(self):
-        if os.path.exists(f"{DirectoryManager.get_config_directory()}/config.toml"):
-            try:
-                with open(f"{DirectoryManager.get_config_directory()}/config.toml", "rb") as f:
-                    data = tomli.load(f)
-
-            except tomli.TOMLDecodeError as e:
-                raise ValueError(f"Invalid TOML configuration: {e}")
-            except Exception as e:
-                raise RuntimeError(f"Error reading configuration: {e}")
-
-            self.__data = data
-            self.database_url = self.__data["database"]["url"]
-            self.database_type = self.__data["database"]["type"]
-
-            if self.__data["settings"]["diary"]["auto_open_diary_on_startup"] == "":
-                self.auto_open_diary = None
-            self.auto_open_new_diary = self.__data["settings"]["diary"]["auto_open_on_creation"]
-        else:
-            print("Error: config.toml not found.")
-            self.create_config()
-            self.read_config()
-
-    def create_config(self, config: dict = None):
-        # Garantir que o diretório de configuração existe
-        config_dir = DirectoryManager.get_config_directory()
-        if not os.path.exists(config_dir):
-            os.makedirs(config_dir, exist_ok=True)
-
-        default = {
-            "database": {
-                "url": f"{config_dir}/database.db",
-                "type": "sqlite"
-            },
-            "settings": {
-                "diary": {
-                    "auto_open_diary_on_startup": "",
-                    "auto_open_on_creation": False
-                }
-            }
-        }
-        if config is None:
-            config = default
-
-        try:
-            with open(f"{config_dir}/config.toml", "wb") as f:
-                tomli_w.dump(config, f)
-        except Exception as e:
-            raise RuntimeError(f"Error creating configuration: {e}")
-
-    def save_config(self):
-        if self.__data is None:
-            self.read_config()
-        if self.__data is None:
-            raise RuntimeError("Error reading configuration.")
-
-        self.__data["database"]["url"] = self.database_url
-        self.__data["database"]["type"] = self.database_type
-        self.__data["settings"]["diary"]["auto_open_diary_on_startup"] = self.auto_open_diary or ""
-        self.__data["settings"]["diary"]["auto_open_on_creation"] = self.auto_open_new_diary
-        try:
-            self.create_config(self.__data)
-        except Exception as e:
-            raise RuntimeError(f"Error saving configuration: {e}")
-
-    def set_config_dir(self, value):
-        self.config_dir = value
-
-    def set_database_url(self, value: str):
-        self.database_url = value
-
-    def set_auto_open_diary(self, value: str):
-        self.auto_open_diary = value
-
-    def set_auto_open_new_diary(self, value: bool):
-        self.auto_open_new_diary = value

src/pilgrim/utils/directory_manager.py

@@ -1,5 +1,4 @@
 import os
-import shutil
 from pathlib import Path
 
 
@@ -38,26 +37,3 @@ class DirectoryManager:
     def get_diary_images_directory(directory_name: str) -> Path:
         """Returns the images directory path for a specific diary."""
         return DirectoryManager.get_diary_data_directory(directory_name) / "images"
-
-    @staticmethod
-    def get_database_path() -> Path:
-        """
-        Get the database file path following XDG Base Directory specification.
-        Creates the directory if it doesn't exist.
-        """
-        pilgrim_dir = DirectoryManager.get_config_directory()
-        db_path = pilgrim_dir / "database.db"
-
-        # If database doesn't exist in new location but exists in current directory,
-        # migrate it
-        if not db_path.exists():
-            current_db = Path("database.db")
-            if current_db.exists():
-                try:
-                    shutil.copy2(current_db, db_path)
-                    # Consider using logging instead of print
-                    print(f"Database migrated from {current_db} to {db_path}")
-                except (OSError, shutil.Error) as e:
-                    raise RuntimeError(f"Failed to migrate database: {e}")
-
-        return db_path