capcat.core.storage_manager

File: Application/capcat/core/storage_manager.py

Description

Storage management component for Capcat.

Handles file system operations, folder creation, and content storage independently from the main article fetching logic.

Classes

StorageManager

Manages all file system operations for article storage.

Methods

init

def __init__(self)

Parameters:

• self

create_article_folder

def create_article_folder(self, base_folder: str, title: str) -> str

Create a folder for storing an article’s content.

Args: base_folder: Base directory to create the article folder in title: Article title to use for folder name

Returns: Path to the created article folder

Parameters:

• self
• base_folder (str)
• title (str)

Returns: str

save_article_content

def save_article_content(self, article_folder_path: str, content: str, title: str) -> str

Save article content to the article folder.

Args: article_folder_path: Path to the article folder content: Content to save title: Article title used to generate the markdown filename

Returns: Path to the saved content file

Parameters:

• self
• article_folder_path (str)
• content (str)
• title (str)

Returns: str

cleanup_empty_images_folder

def cleanup_empty_images_folder(self, article_folder_path: str) -> None

Remove images folder if it exists but is empty.

Args: article_folder_path: Path to the article folder

Parameters:

• self
• article_folder_path (str)

Returns: None

_get_unique_folder_name

def _get_unique_folder_name(self, base_folder: str, base_title: str) -> str

Get folder name - always returns base_title to allow overwrite. When user runs repeatedly, content is replaced instead of creating duplicates.

Parameters:

• self
• base_folder (str)
• base_title (str)

Returns: str

Functions

article_md_filename

def article_md_filename(title: str) -> str

Return sanitized markdown filename for an article (e.g. ‘My-Title.md’).

Truncation respects processing.max_filename_length from config. The total filename length (including ‘.md’) is <= max_filename_length. Spaces are replaced with hyphens.

Parameters:

• title (str)

Returns: str

comments_md_filename

def comments_md_filename(title: str) -> str

Return sanitized markdown filename for comments (e.g. ‘My-Title-Comments.md’).

Truncation respects processing.max_filename_length from config. The total filename length (including ‘-Comments.md’) is <= max_filename_length. Spaces are replaced with hyphens.

Parameters:

• title (str)

Returns: str

find_article_md

def find_article_md(folder: Path) -> 'Path | None'

Return the article markdown path in folder, or None if absent.

Non-recursive: only searches direct children of folder. Returns the first .md file whose stem does not end in ‘-Comments’.

Parameters:

• folder (Path)

find_comments_md

def find_comments_md(folder: Path) -> 'Path | None'

Return the comments markdown path in folder, or None if absent.

Parameters:

• folder (Path)

inject_comments_wikilink

def inject_comments_wikilink(article_folder_path: str, comments_stem: str) -> bool

Idempotent: if line 1 already starts with ‘→ [[’, returns True without modifying. Returns False on any error without raising. Module-level function, not a StorageManager method.

Parameters:

• article_folder_path (str)
• comments_stem (str)

Returns: bool

inject_frontmatter

def inject_frontmatter(md_path: str, metadata: dict) -> bool

Prepend YAML frontmatter to a markdown file.

Idempotent: if the file already starts with ‘—’, returns True without modifying. Omits any key whose value is None. Returns False on any error without raising.

Parameters:

• md_path (str)
• metadata (dict)

Returns: bool

update_frontmatter_pdfs

def update_frontmatter_pdfs(md_path: str, pdf_paths: list) -> bool

Add or replace the ‘pdfs’ key in an existing YAML frontmatter block.

Reads current frontmatter, sets pdfs to pdf_paths, writes back. No-ops (returns True) when pdf_paths is empty. Returns False if no frontmatter exists or on any error.

Parameters:

• md_path (str)
• pdf_paths (list)

Returns: bool