convoviz 0.3.2__tar.gz → 0.3.9__tar.gz

{convoviz-0.3.2 → convoviz-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convoviz
-Version: 0.3.2
+Version: 0.3.9
 Summary: Get analytics and visualizations on your ChatGPT data!
 Keywords: markdown,chatgpt,openai,visualization,analytics,json,export,data-analysis,obsidian
 Author: Mohamed Cheikh Sidiya
@@ -27,9 +27,6 @@ Description-Content-Type: text/markdown
 
 Convert your ChatGPT history into well-formatted Markdown files. Visualize your data with word clouds 🔡☁️ and usage graphs 📈.
 
-![GitHub last commit](https://img.shields.io/github/last-commit/mohamed-chs/chatgpt-history-export-to-md)
-![GitHub issues](https://img.shields.io/github/issues/mohamed-chs/chatgpt-history-export-to-md)
-
 ## Features
 
 - **YAML Headers**: Optional and included by default.
@@ -56,7 +53,7 @@ MacOS / Linux:
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-Windows (PowerShell):
+Windows:
 
 ```powershell
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
@@ -70,6 +67,14 @@ uv tool install "convoviz[viz]"
 
 The `[viz]` extra includes graphs and word clouds. Skip it for a faster markdown-only install.
 
+### Alternative: pip
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install "convoviz[viz]"
+```
+
 ### 3. Run the tool 🏃‍♂️
 
 Simply run the command and follow the prompts:
@@ -101,6 +106,8 @@ Options: `markdown`, `graphs`, `wordclouds`. In interactive mode, you'll be prom
 - `--zip` / `-z` is kept as an alias for `--input` for convenience.
 - You can force non-interactive mode with `--no-interactive`.
 - Use `--flat` to put all Markdown files in a single folder instead of organizing by date.
+- Use `--verbose` or `-v` for detailed logging (use `-vv` for debug logs).
+- Use `--log-file` to specify a custom log file (logs default to a temporary file if not specified).
 
 For more options, run:
 

{convoviz-0.3.2 → convoviz-0.3.9}/README.md

@@ -2,9 +2,6 @@
 
 Convert your ChatGPT history into well-formatted Markdown files. Visualize your data with word clouds 🔡☁️ and usage graphs 📈.
 
-![GitHub last commit](https://img.shields.io/github/last-commit/mohamed-chs/chatgpt-history-export-to-md)
-![GitHub issues](https://img.shields.io/github/issues/mohamed-chs/chatgpt-history-export-to-md)
-
 ## Features
 
 - **YAML Headers**: Optional and included by default.
@@ -31,7 +28,7 @@ MacOS / Linux:
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-Windows (PowerShell):
+Windows:
 
 ```powershell
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
@@ -45,6 +42,14 @@ uv tool install "convoviz[viz]"
 
 The `[viz]` extra includes graphs and word clouds. Skip it for a faster markdown-only install.
 
+### Alternative: pip
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install "convoviz[viz]"
+```
+
 ### 3. Run the tool 🏃‍♂️
 
 Simply run the command and follow the prompts:
@@ -76,6 +81,8 @@ Options: `markdown`, `graphs`, `wordclouds`. In interactive mode, you'll be prom
 - `--zip` / `-z` is kept as an alias for `--input` for convenience.
 - You can force non-interactive mode with `--no-interactive`.
 - Use `--flat` to put all Markdown files in a single folder instead of organizing by date.
+- Use `--verbose` or `-v` for detailed logging (use `-vv` for debug logs).
+- Use `--log-file` to specify a custom log file (logs default to a temporary file if not specified).
 
 For more options, run:
 

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/analysis/graphs.py

@@ -12,6 +12,7 @@ from collections import defaultdict
 from collections.abc import Callable, Iterable
 from datetime import UTC, datetime
 from pathlib import Path
+import logging
 
 import matplotlib.dates as mdates
 import matplotlib.font_manager as fm
@@ -25,6 +26,8 @@ from convoviz.config import GraphConfig, get_default_config
 from convoviz.models import ConversationCollection
 from convoviz.utils import get_asset_path
 
+logger = logging.getLogger(__name__)
+
 WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
 
 
@@ -742,6 +745,7 @@ def generate_summary_graphs(
     cfg = config or get_default_config().graph
 
     user_ts = collection.timestamps("user")
+    logger.info(f"Generating summary graphs to {output_dir}")
 
     tasks: list[tuple[str, str, Callable[[], Figure]]] = [
         ("Overview", "overview.png", lambda: generate_summary_dashboard(collection, cfg)),

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/analysis/wordcloud.py

@@ -4,6 +4,7 @@ import os
 from concurrent.futures import ProcessPoolExecutor
 from functools import lru_cache
 from pathlib import Path
+import logging
 
 from nltk import download as nltk_download
 from nltk.corpus import stopwords as nltk_stopwords
@@ -15,6 +16,8 @@ from wordcloud import WordCloud
 from convoviz.config import WordCloudConfig
 from convoviz.models import ConversationCollection
 
+logger = logging.getLogger(__name__)
+
 # Languages for stopwords
 STOPWORD_LANGUAGES = [
     "arabic",
@@ -149,11 +152,15 @@ def generate_wordclouds(
         progress_bar: Whether to show progress bars
     """
     output_dir.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Generating wordclouds to {output_dir}")
 
     week_groups = collection.group_by_week()
     month_groups = collection.group_by_month()
     year_groups = collection.group_by_year()
 
+    # Pre-load/download NLTK stopwords in the main process to avoid race conditions in workers
+    load_nltk_stopwords()
+
     # Build list of all tasks: (text, filename, output_dir, config)
     tasks: list[tuple[str, str, Path, WordCloudConfig]] = []
 
@@ -185,6 +192,7 @@ def generate_wordclouds(
         max_workers = max(1, cpu_count // 2)
 
     # Use parallel processing for speedup on multi-core systems
+    logger.debug(f"Starting wordcloud generation with {max_workers} workers for {len(tasks)} tasks")
     with ProcessPoolExecutor(max_workers=max_workers) as executor:
         list(
             tqdm(

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/cli.py

@@ -4,6 +4,7 @@ from pathlib import Path
 
 import typer
 from rich.console import Console
+from rich.markup import escape
 
 from convoviz.config import FolderOrganization, OutputKind, get_default_config
 from convoviz.exceptions import ConfigurationError, InvalidZipError
@@ -11,6 +12,8 @@ from convoviz.interactive import run_interactive_config
 from convoviz.io.loaders import find_latest_zip
 from convoviz.pipeline import run_pipeline
 from convoviz.utils import default_font_path
+from convoviz.logging_config import setup_logging
+import logging
 
 app = typer.Typer(
     add_completion=False,
@@ -56,8 +59,26 @@ def run(
         "-i/-I",
         help="Force interactive mode on or off.",
     ),
+    verbose: int = typer.Option(
+        0,
+        "--verbose",
+        "-v",
+        help="Increase verbosity. Use -vv for debug.",
+        count=True,
+    ),
+    log_file: Path | None = typer.Option(
+        None,
+        "--log-file",
+        help="Path to log file. Defaults to a temporary file.",
+    ),
 ) -> None:
     """Convert ChatGPT export data to markdown and generate visualizations."""
+    # Setup logging immediately
+    log_path = setup_logging(verbose, log_file)
+    logger = logging.getLogger("convoviz.cli")
+    console.print(f"[dim]Logging to: {log_path}[/dim]")
+    logger.debug(f"Logging initialized. Output: {log_path}")
+
     if ctx.invoked_subcommand is not None:
         return
 
@@ -113,10 +134,13 @@ def run(
     try:
         run_pipeline(config)
     except (InvalidZipError, ConfigurationError) as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
+        logger.error(f"Known error: {e}")
+        console.print(f"[bold red]Error:[/bold red] {escape(str(e))}")
         raise typer.Exit(code=1) from None
     except Exception as e:
-        console.print(f"[bold red]Unexpected error:[/bold red] {e}")
+        logger.exception("Unexpected error occurred")
+        console.print(f"[bold red]Unexpected error:[/bold red] {escape(str(e))}")
+        console.print(f"[dim]See log file for details: {log_path}[/dim]")
         raise typer.Exit(code=1) from None
 
 

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/interactive.py

@@ -6,6 +6,7 @@ from typing import Literal, Protocol, cast
 from questionary import Choice, Style, checkbox, select
 from questionary import path as qst_path
 from questionary import text as qst_text
+import logging
 
 from convoviz.config import ConvovizConfig, OutputKind, get_default_config
 from convoviz.io.loaders import find_latest_zip, validate_zip
@@ -26,6 +27,8 @@ CUSTOM_STYLE = Style(
     ]
 )
 
+logger = logging.getLogger(__name__)
+
 
 class _QuestionaryPrompt[T](Protocol):
     def ask(self) -> T | None: ...
@@ -74,6 +77,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
         Updated configuration based on user input
     """
     config = initial_config or get_default_config()
+    logger.info("Starting interactive configuration")
 
     # Set sensible defaults if not already set
     if not config.input_path:
@@ -97,6 +101,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
     if input_result:
         config.input_path = Path(input_result)
+    logger.debug(f"User selected input: {config.input_path}")
 
     # Prompt for output folder
     output_result: str = _ask_or_cancel(
@@ -109,6 +114,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
     if output_result:
         config.output_folder = Path(output_result)
+    logger.debug(f"User selected output: {config.output_folder}")
 
     # Prompt for outputs to generate
     output_choices = [
@@ -126,6 +132,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
     )
 
     config.outputs = set(selected_outputs) if selected_outputs else set()
+    logger.debug(f"User selected outputs: {config.outputs}")
 
     # Prompt for markdown settings (only if markdown output is selected)
     if OutputKind.MARKDOWN in config.outputs:
@@ -144,6 +151,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
             )
             if result:
                 setattr(headers, role, result)
+        logger.debug(f"User selected headers: {headers}")
 
         # Prompt for markdown flavor
         flavor_result = cast(
@@ -160,6 +168,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
         if flavor_result:
             config.conversation.markdown.flavor = flavor_result
+        logger.debug(f"User selected flavor: {config.conversation.markdown.flavor}")
 
         # Prompt for YAML headers
         yaml_config = config.conversation.yaml

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/io/assets.py

@@ -2,6 +2,9 @@
 
 import shutil
 from pathlib import Path
+import logging
+
+logger = logging.getLogger(__name__)
 
 
 def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
@@ -26,6 +29,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
     # 1. Try exact match
     exact_path = (source_dir / asset_id).resolve()
     if exact_path.exists() and exact_path.is_file() and exact_path.is_relative_to(source_dir):
+        logger.debug(f"Resolved asset (exact): {asset_id} -> {exact_path}")
         return exact_path
 
     # 2. Try prefix match in root
@@ -37,6 +41,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
             if p.is_file() and p.resolve().is_relative_to(source_dir)
         ]
         if files:
+            logger.debug(f"Resolved asset (prefix root): {asset_id} -> {files[0]}")
             return files[0]
     except Exception:
         pass
@@ -53,6 +58,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
                 if p.is_file() and p.resolve().is_relative_to(dalle_dir)
             ]
             if files:
+                logger.debug(f"Resolved asset (dalle): {asset_id} -> {files[0]}")
                 return files[0]
         except Exception:
             pass
@@ -69,6 +75,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
                     if p.is_file() and p.resolve().is_relative_to(user_dir)
                 ]
                 if files:
+                    logger.debug(f"Resolved asset (user dir): {asset_id} -> {files[0]}")
                     return files[0]
     except Exception:
         pass
@@ -92,7 +99,11 @@ def copy_asset(source_path: Path, dest_dir: Path) -> str:
     dest_path = assets_dir / source_path.name
 
     if not dest_path.exists():
-        shutil.copy2(source_path, dest_path)
+        try:
+            shutil.copy2(source_path, dest_path)
+            logger.debug(f"Copied asset: {source_path.name}")
+        except Exception as e:
+            logger.warning(f"Failed to copy asset {source_path}: {e}")
 
     # Return forward-slash path for Markdown compatibility even on Windows
     return f"assets/{source_path.name}"

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/io/loaders.py

@@ -2,12 +2,15 @@
 
 from pathlib import Path, PurePosixPath
 from zipfile import ZipFile
+import logging
 
 from orjson import loads
 
 from convoviz.exceptions import InvalidZipError
 from convoviz.models import Conversation, ConversationCollection
 
+logger = logging.getLogger(__name__)
+
 
 def _is_safe_zip_member_name(name: str) -> bool:
     """Return True if a ZIP entry name is safe to extract.
@@ -46,6 +49,7 @@ def extract_archive(filepath: Path) -> Path:
     """
     folder = filepath.with_suffix("")
     folder.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Extracting archive: {filepath} to {folder}")
 
     with ZipFile(filepath) as zf:
         for member in zf.infolist():
@@ -115,6 +119,7 @@ def load_collection_from_json(filepath: Path | str) -> ConversationCollection:
         Loaded ConversationCollection object
     """
     filepath = Path(filepath)
+    logger.debug(f"Loading collection from JSON: {filepath}")
     with filepath.open(encoding="utf-8") as f:
         data = loads(f.read())
 

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/io/writers.py

@@ -12,6 +12,9 @@ from convoviz.io.assets import copy_asset, resolve_asset_path
 from convoviz.models import Conversation, ConversationCollection
 from convoviz.renderers import render_conversation
 from convoviz.utils import sanitize
+import logging
+
+logger = logging.getLogger(__name__)
 
 # Month names for folder naming
 _MONTH_NAMES = [
@@ -102,6 +105,7 @@ def save_conversation(
     markdown = render_conversation(conversation, config, headers, asset_resolver=asset_resolver)
     with final_path.open("w", encoding="utf-8") as f:
         f.write(markdown)
+    logger.debug(f"Saved conversation: {final_path}")
 
     # Set modification time
     timestamp = conversation.update_time.timestamp()
@@ -135,6 +139,7 @@ def _generate_year_index(year_dir: Path, year: str) -> None:
 
     index_path = year_dir / "_index.md"
     index_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    logger.debug(f"Generated year index: {index_path}")
 
 
 def _generate_month_index(month_dir: Path, year: str, month: str) -> None:
@@ -162,6 +167,7 @@ def _generate_month_index(month_dir: Path, year: str, month: str) -> None:
 
     index_path = month_dir / "_index.md"
     index_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    logger.debug(f"Generated month index: {index_path}")
 
 
 def save_collection(

convoviz-0.3.9/convoviz/logging_config.py

@@ -0,0 +1,77 @@
+"""Logging configuration for convoviz."""
+
+import logging
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from rich.logging import RichHandler
+
+def setup_logging(
+    verbosity: int = 0,
+    log_file: Optional[Path] = None,
+) -> Path:
+    """Set up logging configuration.
+    
+    Args:
+        verbosity: Level of verbosity (0=WARNING, 1=INFO, 2=DEBUG)
+        log_file: Path to log file. If None, a temporary file is created.
+        
+    Returns:
+        Path to the log file used.
+    """
+    # clear existing handlers
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+    
+    # Determine log level for console
+    if verbosity >= 2:
+        console_level = logging.DEBUG
+    elif verbosity >= 1:
+        console_level = logging.INFO
+    else:
+        console_level = logging.WARNING
+        
+    # Console handler (Rich)
+    console_handler = RichHandler(
+        rich_tracebacks=True,
+        markup=True,
+        show_time=False,
+        show_path=False,
+    )
+    console_handler.setLevel(console_level)
+    
+    # File handler
+    if log_file is None:
+        # Create temp file if not specified
+        tf = tempfile.NamedTemporaryFile(
+            prefix="convoviz_", 
+            suffix=".log", 
+            delete=False
+        )
+        log_file = Path(tf.name)
+        tf.close()
+    
+    # Ensure parent dir exists
+    if not log_file.parent.exists():
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        
+    file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    file_handler.setLevel(logging.DEBUG) # Always log DEBUG to file
+    file_formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    file_handler.setFormatter(file_formatter)
+    
+    # Configure root logger
+    # We set root level to DEBUG so that the handlers can filter as they please
+    root_logger.setLevel(logging.DEBUG)
+    root_logger.addHandler(console_handler)
+    root_logger.addHandler(file_handler)
+    
+    # Reduce noise from explicit libraries if necessary
+    logging.getLogger("matplotlib").setLevel(logging.WARNING)
+    logging.getLogger("PIL").setLevel(logging.WARNING)
+    
+    return log_file

{convoviz-0.3.2 → convoviz-0.3.9}/convoviz/pipeline.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 from shutil import rmtree
+import logging
 
 from rich.console import Console
 
@@ -15,6 +16,7 @@ from convoviz.io.loaders import (
 from convoviz.io.writers import save_collection
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _safe_uri(path: Path) -> str:
@@ -46,6 +48,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
     if not input_path.exists():
         raise InvalidZipError(str(input_path), reason="File does not exist")
 
+    logger.info(f"Starting pipeline with input: {input_path}")
     console.print(f"Loading data from {input_path} [bold yellow]📂[/bold yellow] ...\n")
 
     # Load collection based on input type
@@ -62,6 +65,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
     else:
         # Assume zip
         collection = load_collection_from_zip(input_path)
+    logger.info(f"Loaded collection with {len(collection.conversations)} conversations")
 
     # Try to merge bookmarklet data if available
     bookmarklet_json = find_latest_bookmarklet_json()
@@ -70,6 +74,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
         try:
             bookmarklet_collection = load_collection_from_json(bookmarklet_json)
             collection.update(bookmarklet_collection)
+            logger.info("Merged bookmarklet data")
         except Exception as e:
             console.print(
                 f"[bold yellow]Warning:[/bold yellow] Failed to load bookmarklet data: {e}"
@@ -114,6 +119,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
             folder_organization=config.folder_organization,
             progress_bar=True,
         )
+        logger.info("Markdown generation complete")
         console.print(
             f"\nDone [bold green]✅[/bold green] ! "
             f"Check the output [bold blue]📄[/bold blue] here: {_safe_uri(markdown_folder)} 🔗\n"
@@ -138,6 +144,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
             config.graph,
             progress_bar=True,
         )
+        logger.info("Graph generation complete")
         console.print(
             f"\nDone [bold green]✅[/bold green] ! "
             f"Check the output [bold blue]📈[/bold blue] here: {_safe_uri(graph_folder)} 🔗\n"
@@ -162,6 +169,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
             config.wordcloud,
             progress_bar=True,
         )
+        logger.info("Wordcloud generation complete")
         console.print(
             f"\nDone [bold green]✅[/bold green] ! "
             f"Check the output [bold blue]🔡☁️[/bold blue] here: {_safe_uri(wordcloud_folder)} 🔗\n"

{convoviz-0.3.2 → convoviz-0.3.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "convoviz"
-version = "0.3.2"
+version = "0.3.9"
 description = "Get analytics and visualizations on your ChatGPT data!"
 license = "MIT"
 keywords = [