gedcom-navigator 1.9.4__py3-none-any.whl

gedcom_navigator/__init__.py

@@ -0,0 +1,3 @@
+"""GEDCOM Navigator — powerful tool to explore large GEDCOM family tree files."""
+__version__ = "1.9.4"
+__release_date__ = "2026-05-25"

gedcom_navigator/_scripts/gedcom_config.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+gedcom_config.py
+
+Typed persistence layer for settings.json — no GUI imports.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from gedcom_debug import log_exception
+
+
+class ConfigManager:
+    """Read/write a single settings.json file; all I/O is isolated here."""
+
+    def __init__(self, config_path: Path):
+        """Create a manager backed by the given settings file path."""
+        self._path = config_path
+
+    # ------------------------------------------------------------------
+    # Generic key/value accessors
+    # ------------------------------------------------------------------
+
+    def load_value(self, key, default=None):
+        """Return a saved value for key, or default if it is missing or unreadable."""
+        try:
+            data = json.loads(self._path.read_text(encoding='utf-8'))
+            return data.get(key, default)
+        except Exception:  # pylint: disable=broad-exception-caught
+            log_exception(f"loading setting {key!r} from {self._path}")
+            return default
+
+    def save_value(self, key, value):
+        """Persist a single setting value while preserving other saved settings."""
+        try:
+            data = json.loads(self._path.read_text(encoding='utf-8'))
+        except Exception:  # pylint: disable=broad-exception-caught
+            log_exception(f"reading settings before saving {key!r} to {self._path}")
+            data = {}
+        data[key] = value
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(data, indent=2), encoding='utf-8')
+
+    # ------------------------------------------------------------------
+    # Typed accessors
+    # ------------------------------------------------------------------
+
+    def get_recent_files(self):
+        """Return saved recent GEDCOM file paths, discarding non-string entries."""
+        raw = self.load_value('recent_files', [])
+        return [p for p in raw if isinstance(p, str)]
+
+    def set_recent_files(self, files):
+        """Save the ordered list of recent GEDCOM file paths."""
+        self.save_value('recent_files', files)
+
+    def get_home_person(self, gedcom_path):
+        """Return the saved home person ID for a GEDCOM path, if one exists."""
+        return self.load_value('home_persons', {}).get(gedcom_path)
+
+    def set_home_person(self, gedcom_path, indi_id):
+        """Save the home person ID associated with a GEDCOM path."""
+        home_persons = self.load_value('home_persons', {})
+        home_persons[gedcom_path] = indi_id
+        self.save_value('home_persons', home_persons)
+
+    def get_font_preference(self, valid_sizes):
+        """Return a saved font size preference, falling back to medium if invalid."""
+        pref = self.load_value('font_size', 'medium')
+        return pref if pref in valid_sizes else 'medium'
+
+    def set_font_preference(self, size_name):
+        """Save the selected font size preference name."""
+        self.save_value('font_size', size_name)
+
+    def get_theme_preference(self, valid_themes):
+        """Return a saved theme preference, falling back to System if invalid."""
+        pref = self.load_value('theme', 'System')
+        return pref if pref in valid_themes else 'System'
+
+    def set_theme_preference(self, theme_name):
+        """Save the selected theme preference name."""
+        self.save_value('theme', theme_name)
+
+    def get_window_geometry(self, key):
+        """Return saved window geometry for the given key, if present."""
+        return self.load_value(key)
+
+    def set_window_geometry(self, key, geometry):
+        """Save window geometry under the given settings key."""
+        self.save_value(key, geometry)
+
+    def get_top_n(self, default=3):
+        """Return the positive number of closest matches to show."""
+        val = self.load_value('top_n', default)
+        try:
+            return max(1, int(val))
+        except (TypeError, ValueError):
+            return default
+
+    def set_top_n(self, value):
+        """Save the number of closest matches to show."""
+        self.save_value('top_n', int(value))
+
+    def get_max_depth(self, default=10):
+        """Return the positive maximum ancestor search depth."""
+        val = self.load_value('max_depth', default)
+        try:
+            return max(1, int(val))
+        except (TypeError, ValueError):
+            return default
+
+    def set_max_depth(self, value):
+        """Save the maximum ancestor search depth."""
+        self.save_value('max_depth', int(value))
+
+    def get_fuzzy_threshold(self, default=0.72):
+        """Return the fuzzy match threshold clamped to the inclusive range 0.0 to 1.0."""
+        val = self.load_value('fuzzy_threshold', default)
+        try:
+            return min(1.0, max(0.0, float(val)))
+        except (TypeError, ValueError):
+            return default
+
+    def set_fuzzy_threshold(self, value):
+        """Save the fuzzy match threshold as a floating-point value."""
+        self.save_value('fuzzy_threshold', float(value))
+
+    def get_max_display(self, default=2000):
+        """Return the maximum number of people shown in the search results list."""
+        val = self.load_value('max_display', default)
+        try:
+            return max(1, int(val))
+        except (TypeError, ValueError):
+            return default
+
+    def set_max_display(self, value):
+        """Save the maximum number of people shown in the search results list."""
+        self.save_value('max_display', int(value))
+
+    def get_show_ids(self):
+        """Return whether individual IDs should be shown in the UI."""
+        return bool(self.load_value('show_ids', False))
+
+    def set_show_ids(self, value):
+        """Save whether individual IDs should be shown in the UI."""
+        self.save_value('show_ids', bool(value))
+
+    def get_show_full_gedcom(self):
+        """Return whether the Full GEDCOM Record section should appear in the Profile window."""
+        return bool(self.load_value('show_full_gedcom', False))
+
+    def set_show_full_gedcom(self, value):
+        """Save whether the Full GEDCOM Record section should appear in the Profile window."""
+        self.save_value('show_full_gedcom', bool(value))
+
+    def get_name_order(self):
+        """Return the saved display name order, defaulting to first-name first."""
+        val = self.load_value('name_order', 'first_last')
+        return val if val in ('first_last', 'last_first') else 'first_last'
+
+    def set_name_order(self, value):
+        """Save the display name order preference."""
+        self.save_value('name_order', value)
+
+    def get_hide_tooltips(self):
+        """Return whether tooltips should be suppressed."""
+        return bool(self.load_value('hide_tooltips', False))
+
+    def set_hide_tooltips(self, value):
+        """Save whether tooltips should be suppressed."""
+        self.save_value('hide_tooltips', bool(value))
+
+    def get_default_display(self):
+        """Return the startup Display Pane mode."""
+        val = self.load_value('default_display', 'profile')
+        return val if val in ('profile', 'matches', 'paths') else 'profile'
+
+    def set_default_display(self, value):
+        """Save the startup Display Pane mode."""
+        self.save_value('default_display', value)
+
+    def get_tag_keyword(self, default="DNA"):
+        """Return the saved DNA tag keyword."""
+        val = self.load_value('tag_keyword', default)
+        return val if isinstance(val, str) else default
+
+    def set_tag_keyword(self, value):
+        """Save the DNA tag keyword."""
+        self.save_value('tag_keyword', str(value))
+
+    def get_page_marker(self, default="AncestryDNA Match"):
+        """Return the saved DNA page marker keyword."""
+        val = self.load_value('page_marker', default)
+        return val if isinstance(val, str) else default
+
+    def set_page_marker(self, value):
+        """Save the DNA page marker keyword."""
+        self.save_value('page_marker', str(value))
+
+    def get_language(self):
+        """Return the saved language code (e.g., 'en', 'fr') or 'sys' for system default."""
+        return self.load_value('language', 'sys')
+
+    def set_language(self, lang_code):
+        """Save the selected language code."""
+        self.save_value('language', lang_code)
+
+    # ------------------------------------------------------------------
+    # Platform default path
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def default_path():
+        """Return the platform-specific default settings.json path."""
+        if sys.platform == 'win32':
+            import os
+            base = Path(os.environ.get('APPDATA', Path.home()))
+        elif sys.platform == 'darwin':
+            base = Path.home() / 'Library' / 'Application Support'
+        else:
+            import os
+            base = Path(os.environ.get(
+                'XDG_CONFIG_HOME', Path.home() / '.config'))
+        return base / 'gedcom-navigator' / 'settings.json'

gedcom_navigator/_scripts/gedcom_core.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""
+gedcom_core.py
+
+Compatibility facade for the GEDCOM parser, display formatting, and graph search
+modules used by the CLI and GUI.
+"""
+
+from gedcom_display import describe, lifespan
+from gedcom_parser import (
+    LINE_RE,
+    ZIP_MAX_BYTES,
+    apply_dna_flags,
+    build_model,
+    extract_ged_from_zip,
+    extract_year,
+    iter_records,
+    iter_records_checked,
+)
+from gedcom_search import (
+    SearchCancelled,
+    bfs_find_all_paths,
+    bfs_find_dna_matches,
+    neighbors,
+)
+
+__all__ = [
+    'LINE_RE',
+    'SearchCancelled',
+    'ZIP_MAX_BYTES',
+    'apply_dna_flags',
+    'bfs_find_all_paths',
+    'bfs_find_dna_matches',
+    'build_model',
+    'describe',
+    'extract_ged_from_zip',
+    'extract_year',
+    'iter_records',
+    'iter_records_checked',
+    'lifespan',
+    'neighbors',
+]

gedcom_navigator/_scripts/gedcom_data_model.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""
+gedcom_data_model.py
+
+Data layer: GEDCOM loading, JSON caching, and BFS search.
+Isolated from all GUI concerns — no tkinter imports.
+"""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from gedcom_parser import apply_dna_flags, build_model
+from gedcom_relationship import find_common_ancestors
+from gedcom_search import bfs_find_all_paths, bfs_find_dna_matches
+from gedcom_debug import log_exception
+
+
+def _positive_int(value, name):
+    """Return value as a positive integer or raise ValueError."""
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a positive integer.") from exc
+    if parsed < 1:
+        raise ValueError(f"{name} must be a positive integer.")
+    return parsed
+
+
+class GedcomDataModel:
+    """Owns the parsed GEDCOM state and all I/O against it."""
+
+    # Bump this whenever the cached individual/family schema changes so that
+    # stale cache files are automatically discarded and reparsed.
+    _CACHE_VERSION = 6
+
+    def __init__(self):
+        self.individuals = {}
+        self.families = {}
+        self.tag_records = {}
+        self.married_name_index = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def load(self, gedcom_path, dna_keyword, page_marker, cache_dir):
+        """Parse (or restore from cache) a GEDCOM file.
+
+        Returns (from_cache, encoding_warning, model_error).
+        encoding_warning is a string or None; always None when loaded from cache.
+        model_error is a string or None when parsing did not produce a usable model.
+        """
+        cached = self._load_from_cache(gedcom_path, cache_dir)
+        if cached is not None:
+            self.individuals, self.families, self.tag_records = cached
+            apply_dna_flags(self.individuals, self.tag_records, dna_keyword, page_marker)
+            self.married_name_index = self._build_married_name_index()
+            return True, None, None
+
+        (
+            self.individuals,
+            self.families,
+            self.tag_records,
+            warning,
+            model_error,
+        ) = build_model(
+            gedcom_path,
+            dna_keyword=dna_keyword,
+            page_marker=page_marker,
+        )
+        if model_error:
+            self.individuals = {}
+            self.families = {}
+            self.tag_records = {}
+            self.married_name_index = {}
+            return False, warning, model_error
+        self.married_name_index = self._build_married_name_index()
+        self._save_to_cache(gedcom_path, cache_dir)
+        return False, warning, None
+
+    def reflag(self, dna_keyword, page_marker):
+        """Re-apply DNA flags in-place without re-parsing or touching the cache."""
+        apply_dna_flags(self.individuals, self.tag_records, dna_keyword, page_marker)
+
+    def find_dna_matches(self, start_id, top_n, max_depth, cancel_event=None):
+        """Find the nearest DNA-flagged people to a given individual."""
+        top_n = _positive_int(top_n, "top_n")
+        max_depth = _positive_int(max_depth, "max_depth")
+        return bfs_find_dna_matches(
+            start_id, self.individuals, self.families,
+            top_n=top_n, max_depth=max_depth, cancel_event=cancel_event,
+        )
+
+    def find_all_paths(self, start_id, end_id, top_n, max_depth, cancel_event=None):
+        """Find up to top_n relationship paths between two individuals."""
+        top_n = _positive_int(top_n, "top_n")
+        max_depth = _positive_int(max_depth, "max_depth")
+        return bfs_find_all_paths(
+            start_id, end_id, self.individuals, self.families,
+            top_n=top_n, max_depth=max_depth, cancel_event=cancel_event,
+        )
+
+    def find_common_ancestors(self, start_id, end_id):
+        """Find nearest common biological ancestors between two individuals."""
+        return find_common_ancestors(
+            start_id, end_id, self.individuals, self.families)
+
+    def clear_cache(self, cache_dir):
+        """Delete all .json cache files under cache_dir. Returns count deleted."""
+        deleted = 0
+        try:
+            for f in Path(cache_dir).glob('*.json'):
+                try:
+                    f.unlink()
+                    deleted += 1
+                except OSError:
+                    pass
+        except Exception: # pylint: disable=broad-exception-caught
+            log_exception(f"clearing cache directory {cache_dir!r}")
+            pass
+        return deleted
+
+    def _build_married_name_index(self):
+        """Return derived married-name aliases keyed by wife individual ID."""
+        index = {}
+        for fam in self.families.values():
+            wife_id = fam.get('wife')
+            husb_id = fam.get('husb')
+            if not wife_id or not husb_id:
+                continue
+
+            wife = self.individuals.get(wife_id)
+            husband = self.individuals.get(husb_id)
+            if not wife or not husband:
+                continue
+
+            given_name = wife.get('given_name', '').strip()
+            husband_surname = husband.get('surname', '').strip()
+            if not given_name or not husband_surname:
+                continue
+
+            married_name = f"{given_name} {husband_surname}".strip()
+            if not married_name:
+                continue
+
+            existing_names = set(wife.get('alt_names') or [wife.get('name', '')])
+            existing_names.update(index.get(wife_id, ()))
+            if married_name not in existing_names:
+                index.setdefault(wife_id, []).append(married_name)
+
+        return index
+
+    # ------------------------------------------------------------------
+    # Cache internals
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _cache_path(gedcom_path, cache_dir):
+        key = os.path.normcase(os.path.abspath(gedcom_path)).encode()
+        return Path(cache_dir) / (hashlib.md5(key).hexdigest() + '.json')
+
+    def _load_from_cache(self, gedcom_path, cache_dir):
+        try:
+            cache_file = self._cache_path(gedcom_path, cache_dir)
+            if not cache_file.exists():
+                return None
+            file_mtime = os.path.getmtime(gedcom_path)
+            with cache_file.open('r', encoding='utf-8') as f:
+                data = json.load(f)
+            if (data.get('cache_version') != self._CACHE_VERSION
+                    or data.get('mtime') != file_mtime):
+                return None
+            if not data.get('individuals'):
+                return None
+            return data['individuals'], data['families'], data['tag_records']
+        except Exception: # pylint: disable=broad-exception-caught
+            log_exception(f"loading parse cache for {gedcom_path!r}")
+            return None
+
+    def _save_to_cache(self, gedcom_path, cache_dir):
+        try:
+            cache_dir_path = Path(cache_dir)
+            cache_dir_path.mkdir(parents=True, exist_ok=True)
+            cache_file = self._cache_path(gedcom_path, cache_dir_path)
+            payload = {
+                'cache_version': self._CACHE_VERSION,
+                'mtime': os.path.getmtime(gedcom_path),
+                'individuals': self.individuals,
+                'families': self.families,
+                'tag_records': self.tag_records,
+            }
+            tmp = cache_file.with_suffix('.tmp')
+            with tmp.open('w', encoding='utf-8') as f:
+                json.dump(payload, f)
+            tmp.replace(cache_file)
+        except Exception: # pylint: disable=broad-exception-caught
+            log_exception(f"saving parse cache for {gedcom_path!r}")
+            pass

gedcom_navigator/_scripts/gedcom_debug.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""
+gedcom_debug.py
+
+Debug-only exception logging and process-wide exception hooks.
+"""
+
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+from pathlib import Path
+import sys
+import tempfile
+import threading
+
+
+_DEBUG_ENV = 'GEDCOM_NAVIGATOR_DEBUG'
+_LOG_PATH_ENV = 'GEDCOM_NAVIGATOR_DEBUG_LOG'
+_LOGGER_NAME = 'gedcom_navigator'
+_MAX_LOG_BYTES = 1_000_000
+_BACKUP_COUNT = 3
+
+_configured_path = None
+_previous_sys_excepthook = None
+_previous_threading_excepthook = None
+_previous_tk_report_callback_exception = None
+_logged_exception_keys = set()
+
+
+def _getenv(name, default=None):
+    """Return an environment value using case-insensitive lookup on all platforms."""
+    value = os.environ.get(name)
+    if value is not None:
+        return value
+    name_upper = name.upper()
+    for key, candidate in os.environ.items():
+        if key.upper() == name_upper:
+            return candidate
+    return default
+
+
+def debug_enabled():
+    """Return whether debug diagnostics are enabled for this process."""
+    return _getenv(_DEBUG_ENV, '').strip().lower() in {
+        '1', 'true', 'yes', 'on'
+    }
+
+
+def set_debug_enabled(enabled=True):
+    """Set or clear the environment flag used by all debug-only helpers."""
+    if enabled:
+        os.environ[_DEBUG_ENV] = '1'
+    else:
+        os.environ.pop(_DEBUG_ENV, None)
+
+
+def _default_debug_log_path():
+    if sys.platform == 'win32':
+        base = Path(os.environ.get('APPDATA', Path.home()))
+    elif sys.platform == 'darwin':
+        base = Path.home() / 'Library' / 'Application Support'
+    else:
+        base = Path(os.environ.get('XDG_CONFIG_HOME', Path.home() / '.config'))
+    return base / 'gedcom-navigator' / 'debug.log'
+
+
+def debug_log_path():
+    """Return the configured debug log path."""
+    override = _getenv(_LOG_PATH_ENV)
+    if override:
+        return Path(override).expanduser()
+    return _default_debug_log_path()
+
+
+def get_debug_logger():
+    """Return the application debug logger."""
+    return logging.getLogger(_LOGGER_NAME)
+
+
+def configure_debug_logging(*, enabled=None):
+    """Configure rotating file logging when debug mode is enabled."""
+    global _configured_path
+
+    if enabled is not None:
+        set_debug_enabled(enabled)
+    if not debug_enabled():
+        return None
+
+    logger = get_debug_logger()
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+
+    if _configured_path is not None:
+        return _configured_path
+
+    path = debug_log_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handler = RotatingFileHandler(
+            path,
+            maxBytes=_MAX_LOG_BYTES,
+            backupCount=_BACKUP_COUNT,
+            encoding='utf-8',
+        )
+    except OSError:
+        fallback_dir = Path(tempfile.gettempdir())
+        path = fallback_dir / 'gedcom-navigator-debug.log'
+        fallback_dir.mkdir(parents=True, exist_ok=True)
+        handler = RotatingFileHandler(
+            path,
+            maxBytes=_MAX_LOG_BYTES,
+            backupCount=_BACKUP_COUNT,
+            encoding='utf-8',
+        )
+
+    handler.setLevel(logging.DEBUG)
+    handler.setFormatter(logging.Formatter(
+        '%(asctime)s %(levelname)s [%(threadName)s] %(name)s: %(message)s'
+    ))
+    logger.addHandler(handler)
+    _configured_path = path
+    logger.debug(
+        'Debug logging enabled: executable=%r argv=%r log_path=%s',
+        sys.executable,
+        sys.argv,
+        path,
+    )
+    return path
+
+
+def log_debug(message, *args, **kwargs):
+    """Write a debug message if diagnostics are enabled."""
+    if not debug_enabled():
+        return
+    configure_debug_logging()
+    get_debug_logger().debug(message, *args, **kwargs)
+
+
+def log_exception(context):
+    """Log the active exception if diagnostics are enabled."""
+    if not debug_enabled():
+        return
+    configure_debug_logging()
+    get_debug_logger().debug('Recovered exception: %s', context, exc_info=True)
+
+
+def log_exception_once(key, context):
+    """Log the active exception once per key if diagnostics are enabled."""
+    if key in _logged_exception_keys:
+        return
+    _logged_exception_keys.add(key)
+    log_exception(context)
+
+
+def _log_unhandled_exception(context, exc_info):
+    configure_debug_logging()
+    get_debug_logger().critical(context, exc_info=exc_info)
+
+
+def install_exception_hooks(root=None):
+    """Install process-wide debug hooks for uncaught exceptions."""
+    global _previous_sys_excepthook
+    global _previous_threading_excepthook
+    global _previous_tk_report_callback_exception
+
+    if not debug_enabled():
+        return
+    configure_debug_logging()
+
+    if _previous_sys_excepthook is None:
+        _previous_sys_excepthook = sys.excepthook
+
+        def _sys_excepthook(exc_type, exc_value, traceback):
+            _log_unhandled_exception(
+                'Unhandled main-thread exception',
+                (exc_type, exc_value, traceback),
+            )
+            _previous_sys_excepthook(exc_type, exc_value, traceback)
+
+        sys.excepthook = _sys_excepthook
+
+    if (_previous_threading_excepthook is None
+            and hasattr(threading, 'excepthook')):
+        _previous_threading_excepthook = threading.excepthook
+
+        def _threading_excepthook(args):
+            _log_unhandled_exception(
+                f'Unhandled thread exception in {args.thread!r}',
+                (args.exc_type, args.exc_value, args.exc_traceback),
+            )
+            _previous_threading_excepthook(args)
+
+        threading.excepthook = _threading_excepthook
+
+    if root is not None and _previous_tk_report_callback_exception is None:
+        _previous_tk_report_callback_exception = root.report_callback_exception
+
+        def _report_callback_exception(exc_type, exc_value, traceback):
+            _log_unhandled_exception(
+                'Unhandled Tk callback exception',
+                (exc_type, exc_value, traceback),
+            )
+            _previous_tk_report_callback_exception(
+                exc_type, exc_value, traceback)
+
+        root.report_callback_exception = _report_callback_exception