rolfedh-doc-utils 0.1.14__py3-none-any.whl → 0.1.16__py3-none-any.whl

archive_unused_files.py

@@ -9,10 +9,13 @@ For full documentation and usage examples, see archive_unused_files.md in this d
 
 import argparse
 from doc_utils.unused_adoc import find_unused_adoc
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import parse_exclude_list_file
 
 from doc_utils.spinner import Spinner
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(
         description='Archive unused AsciiDoc files.',
         epilog='By default, automatically discovers all modules and assemblies directories in the repository.'

archive_unused_images.py

@@ -8,10 +8,13 @@ For full documentation and usage examples, see archive_unused_files.md in this d
 
 import argparse
 from doc_utils.unused_images import find_unused_images
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import parse_exclude_list_file
 
 from doc_utils.spinner import Spinner
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(description='Archive unused image files.')
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')

check_scannability.py

@@ -17,6 +17,7 @@ import sys
 import argparse
 from datetime import datetime
 from doc_utils.scannability import check_scannability
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import collect_files, parse_exclude_list_file
 
 from doc_utils.spinner import Spinner
@@ -27,6 +28,8 @@ def print_help():
     print(__doc__)
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     # Manual check for -h or --help to display the full docstring
     if '-h' in sys.argv or '--help' in sys.argv:
         print_help()

doc_utils/extract_link_attributes.py

@@ -235,13 +235,14 @@ def select_link_text(url: str, variations: List[Tuple[str, str, str, int]], inte
             return most_common[0]
 
 
-def collect_all_macros(scan_dirs: List[str] = None, macro_type: str = 'both') -> List[Tuple[str, str, str, str, int]]:
+def collect_all_macros(scan_dirs: List[str] = None, macro_type: str = 'both', exclude_files: List[str] = None) -> List[Tuple[str, str, str, str, int]]:
     """
     Collect all link/xref macros with attributes from all .adoc files.
 
     Args:
         scan_dirs: Directories to scan (default: current directory)
         macro_type: Type of macros to find - 'link', 'xref', or 'both' (default: 'both')
+        exclude_files: List of file paths to exclude from scanning (typically all attributes files)
 
     Returns: List[(file_path, full_macro, url, link_text, line_number)]
     """
@@ -250,6 +251,13 @@ def collect_all_macros(scan_dirs: List[str] = None, macro_type: str = 'both') ->
 
     all_macros = []
 
+    # Normalize all exclude file paths
+    exclude_paths = set()
+    if exclude_files:
+        for file in exclude_files:
+            if file:  # Check for None or empty string
+                exclude_paths.add(os.path.abspath(file))
+
     for scan_dir in scan_dirs:
         for root, _, files in os.walk(scan_dir):
             # Skip hidden directories and .archive
@@ -259,6 +267,9 @@ def collect_all_macros(scan_dirs: List[str] = None, macro_type: str = 'both') ->
             for file in files:
                 if file.endswith('.adoc'):
                     file_path = os.path.join(root, file)
+                    # Skip any attributes files to prevent self-referencing
+                    if exclude_paths and os.path.abspath(file_path) in exclude_paths:
+                        continue
                     macros = find_link_macros(file_path, macro_type)
                     for full_macro, url, link_text, line_num in macros:
                         all_macros.append((file_path, full_macro, url, link_text, line_num))
@@ -510,11 +521,20 @@ def extract_link_attributes(attributes_file: str = None,
     existing_attrs = load_existing_attributes(attributes_file)
     spinner.stop(f"Loaded {len(existing_attrs)} existing attributes")
 
-    # Collect all macros
+    # Find all attributes files to exclude from processing
+    all_attribute_files = find_attribute_files()
+
+    # Notify user about excluded files if there are multiple
+    if len(all_attribute_files) > 1:
+        print(f"Excluding {len(all_attribute_files)} attributes files from processing:")
+        for f in all_attribute_files:
+            print(f"  - {f}")
+
+    # Collect all macros, excluding ALL attributes files
     macro_desc = {'link': 'link', 'xref': 'xref', 'both': 'link and xref'}[macro_type]
     spinner = Spinner(f"Scanning for {macro_desc} macros with attributes")
     spinner.start()
-    all_macros = collect_all_macros(scan_dirs, macro_type)
+    all_macros = collect_all_macros(scan_dirs, macro_type, exclude_files=all_attribute_files)
     spinner.stop()
 
     if not all_macros:

doc_utils/version_check.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+Version checking utility for doc-utils.
+
+Checks PyPI for the latest version and notifies users if an update is available.
+Includes caching to avoid excessive PyPI requests.
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timedelta
+from importlib.metadata import version as get_installed_version
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def get_cache_dir() -> Path:
+    """Get the cache directory for version check data."""
+    # Use XDG_CACHE_HOME if set, otherwise ~/.cache
+    cache_home = os.environ.get('XDG_CACHE_HOME')
+    if cache_home:
+        cache_dir = Path(cache_home) / 'doc-utils'
+    else:
+        cache_dir = Path.home() / '.cache' / 'doc-utils'
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def get_cache_file() -> Path:
+    """Get the cache file path."""
+    return get_cache_dir() / 'version_check.json'
+
+
+def read_cache() -> Optional[dict]:
+    """Read version check cache."""
+    cache_file = get_cache_file()
+    if not cache_file.exists():
+        return None
+
+    try:
+        with open(cache_file, 'r') as f:
+            data = json.load(f)
+            # Check if cache is still valid (24 hours)
+            last_check = datetime.fromisoformat(data['last_check'])
+            if datetime.now() - last_check < timedelta(hours=24):
+                return data
+    except (json.JSONDecodeError, KeyError, ValueError):
+        pass
+
+    return None
+
+
+def write_cache(latest_version: str, current_version: str):
+    """Write version check cache."""
+    cache_file = get_cache_file()
+    data = {
+        'last_check': datetime.now().isoformat(),
+        'latest_version': latest_version,
+        'current_version': current_version,
+    }
+
+    try:
+        with open(cache_file, 'w') as f:
+            json.dump(data, f)
+    except Exception:
+        # Silently fail if we can't write cache
+        pass
+
+
+def fetch_latest_version() -> Optional[str]:
+    """Fetch the latest version from PyPI."""
+    try:
+        # Use PyPI JSON API
+        url = 'https://pypi.org/pypi/rolfedh-doc-utils/json'
+        with urllib.request.urlopen(url, timeout=2) as response:
+            data = json.loads(response.read())
+            return data['info']['version']
+    except (urllib.error.URLError, json.JSONDecodeError, KeyError, TimeoutError):
+        # Silently fail if we can't reach PyPI
+        return None
+
+
+def parse_version(version_str: str) -> Tuple[int, ...]:
+    """Parse version string into tuple of integers for comparison."""
+    try:
+        # Remove any pre-release or dev suffixes
+        version_str = version_str.split('+')[0].split('-')[0]
+        return tuple(int(x) for x in version_str.split('.'))
+    except (ValueError, AttributeError):
+        return (0,)
+
+
+def check_for_update(force_check: bool = False) -> Optional[str]:
+    """
+    Check if a newer version is available.
+
+    Args:
+        force_check: If True, bypass cache and always check PyPI
+
+    Returns:
+        The latest version string if an update is available, None otherwise
+    """
+    try:
+        current_version = get_installed_version('rolfedh-doc-utils')
+    except Exception:
+        # Can't determine installed version
+        return None
+
+    # Check cache first (unless forced)
+    if not force_check:
+        cache_data = read_cache()
+        if cache_data:
+            latest_version = cache_data['latest_version']
+            # Only notify if there's a newer version
+            if parse_version(latest_version) > parse_version(current_version):
+                return latest_version
+            return None
+
+    # Fetch from PyPI
+    latest_version = fetch_latest_version()
+    if not latest_version:
+        return None
+
+    # Cache the result
+    write_cache(latest_version, current_version)
+
+    # Check if update is available
+    if parse_version(latest_version) > parse_version(current_version):
+        return latest_version
+
+    return None
+
+
+def show_update_notification(latest_version: str, current_version: str = None):
+    """Show update notification to user."""
+    if not current_version:
+        try:
+            current_version = get_installed_version('rolfedh-doc-utils')
+        except Exception:
+            current_version = 'unknown'
+
+    # Use stderr to avoid interfering with tool output
+    print(f"\n📦 Update available: {current_version} → {latest_version}", file=sys.stderr)
+    print(f"   Run: pip install --upgrade rolfedh-doc-utils", file=sys.stderr)
+    print("", file=sys.stderr)
+
+
+def check_version_on_startup():
+    """
+    Check for updates on tool startup.
+
+    This should be called early in the main() function of each CLI tool.
+    It runs asynchronously and won't block the tool execution.
+    """
+    # Skip version check in certain conditions
+    if any([
+        os.environ.get('DOC_UTILS_NO_VERSION_CHECK'),  # User opt-out
+        os.environ.get('CI'),  # Running in CI
+        not sys.stderr.isatty(),  # Not running in terminal
+    ]):
+        return
+
+    try:
+        latest_version = check_for_update()
+        if latest_version:
+            show_update_notification(latest_version)
+    except Exception:
+        # Never let version checking break the tool
+        pass
+
+
+def disable_version_check():
+    """
+    Instructions for disabling version check.
+
+    Users can disable by setting DOC_UTILS_NO_VERSION_CHECK environment variable.
+    """
+    print("To disable version checking, set the environment variable:")
+    print("  export DOC_UTILS_NO_VERSION_CHECK=1")
+    print("\nOr add it to your shell configuration file.")
+
+
+if __name__ == "__main__":
+    # For testing/debugging
+    import argparse
+    parser = argparse.ArgumentParser(description="Check for doc-utils updates")
+    parser.add_argument('--force', action='store_true', help='Force check (bypass cache)')
+    parser.add_argument('--disable-instructions', action='store_true',
+                       help='Show instructions for disabling version check')
+    args = parser.parse_args()
+
+    if args.disable_instructions:
+        disable_version_check()
+    else:
+        latest = check_for_update(force_check=args.force)
+        if latest:
+            show_update_notification(latest)
+        else:
+            print("You are running the latest version!")

extract_link_attributes.py

@@ -10,9 +10,12 @@ attribute references.
 import argparse
 import sys
 from doc_utils.extract_link_attributes import extract_link_attributes
+from doc_utils.version_check import check_version_on_startup
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     """Main entry point for the extract-link-attributes CLI tool."""
     parser = argparse.ArgumentParser(
         description='Extract link and xref macros containing attributes into attribute definitions',

find_unused_attributes.py

@@ -14,8 +14,11 @@ import sys
 from datetime import datetime
 from doc_utils.unused_attributes import find_unused_attributes, find_attributes_files, select_attributes_file
 from doc_utils.spinner import Spinner
+from doc_utils.version_check import check_version_on_startup
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(description='Find unused AsciiDoc attributes.')
     parser.add_argument(
         'attributes_file',

format_asciidoc_spacing.py

@@ -10,6 +10,7 @@ import sys
 from pathlib import Path
 
 from doc_utils.format_asciidoc_spacing import process_file, find_adoc_files
+from doc_utils.version_check import check_version_on_startup
 
 
 from doc_utils.spinner import Spinner
@@ -27,6 +28,8 @@ def print_colored(message: str, color: str = Colors.NC) -> None:
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     """Main entry point"""
     parser = argparse.ArgumentParser(
         description="Format AsciiDoc files to ensure proper spacing",

replace_link_attributes.py

@@ -19,6 +19,7 @@ from doc_utils.replace_link_attributes import (
     replace_link_attributes_in_file,
     find_adoc_files
 )
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.spinner import Spinner
 
 
@@ -83,6 +84,8 @@ def prompt_for_attributes_file(attributes_files: list[Path]) -> Optional[Path]:
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(
         description='Replace AsciiDoc attributes within link macros with their actual values.'
     )
@@ -155,8 +158,18 @@ def main():
     adoc_files = find_adoc_files(repo_root)
     spinner.stop()
 
-    # Exclude the attributes file itself
-    adoc_files = [f for f in adoc_files if f != attributes_file]
+    # Find ALL attributes files to exclude from processing
+    all_attribute_files = find_attributes_files(repo_root)
+    exclude_paths = {f.resolve() for f in all_attribute_files}
+
+    # Notify user about excluded files if there are multiple
+    if len(all_attribute_files) > 1:
+        print(f"Excluding {len(all_attribute_files)} attributes files from processing:")
+        for f in all_attribute_files:
+            print(f"  - {f.relative_to(repo_root)}")
+
+    # Exclude ALL attributes files, not just the selected one
+    adoc_files = [f for f in adoc_files if f.resolve() not in exclude_paths]
 
     print(f"Found {len(adoc_files)} AsciiDoc files to process")
 

{rolfedh_doc_utils-0.1.14.dist-info → rolfedh_doc_utils-0.1.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.14
+Version: 0.1.16
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -190,11 +190,27 @@ Before submitting PRs:
 
 ## 📊 Project Status
 
-- **Latest Version**: 0.1.6
+- **Latest Version**: 0.1.16 (with automatic update notifications)
 - **Python Support**: 3.8+
-- **Test Coverage**: 66+ tests (100% passing)
+- **Test Coverage**: 112+ tests (100% passing)
 - **Dependencies**: Minimal (PyYAML for OpenShift-docs support)
 
+### 🔔 Update Notifications
+
+All tools now check for updates automatically and notify you when a new version is available:
+
+```
+📦 Update available: 0.1.15 → 0.1.16
+   Run: pip install --upgrade rolfedh-doc-utils
+```
+
+To disable update checks, set the environment variable:
+```bash
+export DOC_UTILS_NO_VERSION_CHECK=1
+```
+
+Update checks are cached for 24 hours to minimize network requests.
+
 ## 🔗 Resources
 
 - [Documentation](https://rolfedh.github.io/doc-utils/)

rolfedh_doc_utils-0.1.16.dist-info/RECORD

@@ -0,0 +1,27 @@
+archive_unused_files.py,sha256=VL4hEN40CTYJzScyevY1fn7Fs2O083qfJUYdrv5JxxM,2142
+archive_unused_images.py,sha256=uZ4-OSMja98toyraDaeG6OMjV7kU2hq-QsTjnDl-BfQ,1732
+check_scannability.py,sha256=IdHwzQtBWzx95zIDOx3B7OyzoKxTVtpn0wJUErFQRC0,5346
+extract_link_attributes.py,sha256=bfWC6h4QWj6YvwZ3-tc3K7oMC2wN4QdA4YMCKcYdKCg,3384
+find_unused_attributes.py,sha256=v1IPuM5RAN9JZwWnOilgXlMCC2kNA5umiyCJ-pyIumI,3456
+format_asciidoc_spacing.py,sha256=B3Bo68_i_RJNlUdNLZ4TiYUslrbwhSkzX3Dyd9JWRo0,4080
+replace_link_attributes.py,sha256=OGD-COUG3JUCYOoARa32xqaSEcA-p31AJLk-d-FPUUQ,7492
+validate_links.py,sha256=KmN4dULwLiLM2lUyteXwbBuTuQHcNkCq0nhiaZ48BtI,6013
+doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
+doc_utils/extract_link_attributes.py,sha256=U0EvPZReJQigNfbT-icBsVT6Li64hYki5W7MQz6qqbc,22743
+doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
+doc_utils/format_asciidoc_spacing.py,sha256=XnVJekaj39aDzjV3xFKl58flM41AaJzejxNYJIIAMz0,10139
+doc_utils/replace_link_attributes.py,sha256=gmAs68_njBqEz-Qni-UGgeYEDTMxlTWk_IOm76FONNE,7279
+doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
+doc_utils/spinner.py,sha256=lJg15qzODiKoR0G6uFIk2BdVNgn9jFexoTRUMrjiWvk,3554
+doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o,4571
+doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
+doc_utils/unused_attributes.py,sha256=EjTtWIKW_aXsR1JOgw5RSDVAqitJ_NfRMVOXVGaiWTY,5282
+doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
+doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
+doc_utils/version_check.py,sha256=1ySC6Au21OqUMZr7AkIa3nMNh3M6wLQmPQCi-ZFIqoE,6338
+rolfedh_doc_utils-0.1.16.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.16.dist-info/METADATA,sha256=quUI6eIDAbfEKSAELOZtyy5be7CfnLBJsvDN0TBU50E,7824
+rolfedh_doc_utils-0.1.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.16.dist-info/entry_points.txt,sha256=2J4Ojc3kkuArpe2xcUOPc0LxSWCmnctvw8hy8zpnbO4,418
+rolfedh_doc_utils-0.1.16.dist-info/top_level.txt,sha256=1w0JWD7w7gnM5Sga2K4fJieNZ7CHPTAf0ozYk5iIlmo,182
+rolfedh_doc_utils-0.1.16.dist-info/RECORD,,

validate_links.py

@@ -12,10 +12,13 @@ import argparse
 import sys
 import json
 from doc_utils.validate_links import LinkValidator, parse_transpositions, format_results
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.spinner import Spinner
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     """Main entry point for the validate-links CLI tool."""
     parser = argparse.ArgumentParser(
         description='Validate links in AsciiDoc documentation',

rolfedh_doc_utils-0.1.14.dist-info/RECORD

@@ -1,26 +0,0 @@
-archive_unused_files.py,sha256=h7CRwSPBVCOQs0hn_ASD4EXz8QJFcAO2x3KX9FVhXNM,1974
-archive_unused_images.py,sha256=4GSVPYkxqFoY-isy47P_1AhD1ziXgmajFiBGCtZ3olg,1564
-check_scannability.py,sha256=MvGLW4UGGcx-jZLsVRYXpXNAIEQyJZZnsN99zJzbtyc,5178
-extract_link_attributes.py,sha256=grPvVwOF9kqIOZ_uxYtJTkO3C2DNtIpKNPp6LlGK3Xs,3216
-find_unused_attributes.py,sha256=IUJKJr_MzxBXqg9rafUs9Kwi8AbU0x-H0AVflc1dhCU,3288
-format_asciidoc_spacing.py,sha256=_XpHqxYWm1AnZLUK_cDpfAJtsDCDF0b66m3opfYnIuU,3912
-replace_link_attributes.py,sha256=XpgdJN56yI-udrZYEnPjw79gFLYTjJdGRk2MA1JoXnI,6830
-validate_links.py,sha256=409fTAyBGTUrp6iSWuJ9AXExcdz8dC_4QeA_RvCIhus,5845
-doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
-doc_utils/extract_link_attributes.py,sha256=TSXrPB5BLMtvuYQ0y8vwg2q9qDSugQC4BoHOpLRaYLA,21748
-doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
-doc_utils/format_asciidoc_spacing.py,sha256=XnVJekaj39aDzjV3xFKl58flM41AaJzejxNYJIIAMz0,10139
-doc_utils/replace_link_attributes.py,sha256=gmAs68_njBqEz-Qni-UGgeYEDTMxlTWk_IOm76FONNE,7279
-doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
-doc_utils/spinner.py,sha256=lJg15qzODiKoR0G6uFIk2BdVNgn9jFexoTRUMrjiWvk,3554
-doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o,4571
-doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
-doc_utils/unused_attributes.py,sha256=EjTtWIKW_aXsR1JOgw5RSDVAqitJ_NfRMVOXVGaiWTY,5282
-doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
-doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
-rolfedh_doc_utils-0.1.14.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.14.dist-info/METADATA,sha256=CK1mmV7kV3d1dtTw9iRdM2N_ztFE1IpN7pWi8BF_YoE,7386
-rolfedh_doc_utils-0.1.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.14.dist-info/entry_points.txt,sha256=2J4Ojc3kkuArpe2xcUOPc0LxSWCmnctvw8hy8zpnbO4,418
-rolfedh_doc_utils-0.1.14.dist-info/top_level.txt,sha256=1w0JWD7w7gnM5Sga2K4fJieNZ7CHPTAf0ozYk5iIlmo,182
-rolfedh_doc_utils-0.1.14.dist-info/RECORD,,