pycodetags 0.1.0__py3-none-any.whl

code_tags/__about__.py

@@ -0,0 +1,8 @@
+"""Metadata for code_tags."""
+
+__all__ = ["__title__", "__version__", "__description__", "__requires_python__"]
+
+__title__ = "code_tags"
+__version__ = "0.1.0"
+__description__ = "TODOs in source code as a first class construct"
+__requires_python__ = ">=3.9"

code_tags/__init__.py

@@ -0,0 +1,38 @@
+"""
+Code Tags is a tool and library for putting TODOs into source code.
+
+Only the strongly typed decorators, exceptions and context managers are exported.
+
+Everything else is a tool.
+"""
+
+__all__ = [
+    "TODO",
+    "FIXME",
+    "TodoException",
+    "REQUIREMENT",
+    "STORY",
+    "IDEA",
+    "BUG",
+    "HACK",
+    "CLEVER",
+    "MAGIC",
+    "ALERT",
+    "PORT",
+    "DOCUMENT",
+]
+
+from code_tags.todo_tag_types import TODO, TodoException
+from code_tags.todo_tag_types_aliases import (
+    ALERT,
+    BUG,
+    CLEVER,
+    DOCUMENT,
+    FIXME,
+    HACK,
+    IDEA,
+    MAGIC,
+    PORT,
+    REQUIREMENT,
+    STORY,
+)

code_tags/__main__.py

@@ -0,0 +1,233 @@
+"""
+CLI for code_tags.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import logging.config
+import sys
+from collections.abc import Sequence
+
+import pluggy
+
+import code_tags.__about__ as __about__
+from code_tags.aggregate import aggregate_all_kinds, aggregate_all_kinds_multiple_input, merge_collected
+from code_tags.collection_types import CollectedTODOs
+from code_tags.config import CodeTagsConfig, get_code_tags_config
+from code_tags.dotenv import load_dotenv
+from code_tags.logging_config import generate_config
+from code_tags.plugin_diagnostics import plugin_currently_loaded
+from code_tags.plugin_manager import get_plugin_manager
+from code_tags.views import (
+    print_changelog,
+    print_done_file,
+    print_html,
+    print_json,
+    print_text,
+    print_todo_md,
+    print_validate,
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """
+    Main entry point for the code_tags CLI.
+
+    Args:
+        argv (Sequence[str] | None): Command line arguments. If None, uses sys.argv.
+    """
+    pm = get_plugin_manager()
+
+    class InternalViews:
+        """Register internal views as a plugin"""
+
+        @pluggy.HookimplMarker("code_tags")
+        def code_tags_print_report(self, format_name: str, found_data: CollectedTODOs) -> bool:
+            """
+            Internal method to handle printing of reports in various formats.
+
+            Args:
+                format_name (str): The name of the format requested by the user.
+                found_data (CollectedTODOs): The data collected from the source code.
+
+            Returns:
+                bool: True if the format was handled, False otherwise.
+            """
+            if format_name == "text":
+                print_text(found_data)
+                return True
+            if format_name == "html":
+                print_html(found_data)
+                return True
+            if format_name == "json":
+                print_json(found_data)
+                return True
+            if format_name == "keep-a-changelog":
+                print_changelog(found_data)
+                return True
+            if format_name == "todo.md":
+                print_todo_md(found_data)
+                return True
+            if format_name == "done":
+                print_done_file(found_data)
+                return True
+            return False
+
+    pm.register(InternalViews())
+    # --- end pluggy setup ---
+
+    parser = argparse.ArgumentParser(description=f"{__about__.__description__} (v{__about__.__version__})")
+
+    # Basic arguments that apply to all commands (like verbose/info/bug-trail/config)
+    base_parser = argparse.ArgumentParser(add_help=False)
+    base_parser.add_argument("--config", help="Path to config file, defaults to current folder pyproject.toml")
+    base_parser.add_argument("--verbose", default=False, action="store_true", help="verbose level logging output")
+    base_parser.add_argument("--info", default=False, action="store_true", help="info level logging output")
+    base_parser.add_argument("--bug-trail", default=False, action="store_true", help="enable bug trail, local logging")
+    # validate switch
+    base_parser.add_argument("--validate", action="store_true", help="Validate all the items found")
+
+    # Create subparsers for commands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # 'report' command
+    report_parser = subparsers.add_parser("report", parents=[base_parser], help="Generate code tag reports")
+    # report runs collectors, collected things can be validated
+    report_parser.add_argument("--module", action="append", help="Python module to inspect (e.g., 'my_project.main')")
+    report_parser.add_argument("--src", action="append", help="file or folder of source code")
+
+    report_parser.add_argument("--output", help="destination file or folder")
+
+    extra_supported_formats = []
+    for result in pm.hook.code_tags_print_report_style_name():
+        extra_supported_formats.extend(result)
+
+    report_parser.add_argument(
+        "--format",
+        choices=["text", "html", "json", "keep-a-changelog", "todo.md", "done"] + extra_supported_formats,
+        default="text",
+        help="Output format for the report.",
+    )
+    # report_parser.add_argument("--validate", action="store_true", help="Validate all the items found")
+
+    _plugin_info_parser = subparsers.add_parser(
+        "plugin-info", parents=[base_parser], help="Display information about loaded plugins"
+    )
+
+    # Allow plugins to add their own subparsers
+    new_subparsers = pm.hook.code_tags_add_cli_subcommands(subparsers=subparsers)
+    # Hack because we don't want plugins to have to wire up the basic stuff
+    for new_subparser in new_subparsers:
+        new_subparser.add_argument("--config", help="Path to config file, defaults to current folder pyproject.toml")
+        new_subparser.add_argument("--verbose", default=False, action="store_true", help="verbose level logging output")
+        new_subparser.add_argument("--info", default=False, action="store_true", help="info level logging output")
+        new_subparser.add_argument(
+            "--bug-trail", default=False, action="store_true", help="enable bug trail, local logging"
+        )
+        # validate switch
+        new_subparser.add_argument("--validate", action="store_true", help="Validate all the items found")
+
+    args = parser.parse_args(args=argv)
+
+    if args.config:
+        code_tags_config = CodeTagsConfig(pyproject_path=args.config)
+    else:
+        code_tags_config = CodeTagsConfig()
+
+    if code_tags_config.use_dot_env():
+        load_dotenv()
+
+    if args.verbose:
+        config = generate_config(level="DEBUG", enable_bug_trail=args.bug_trail)
+        logging.config.dictConfig(config)
+    elif args.info:
+        config = generate_config(level="INFO", enable_bug_trail=args.bug_trail)
+        logging.config.dictConfig(config)
+    else:
+        # Essentially, quiet mode
+        config = generate_config(level="FATAL", enable_bug_trail=args.bug_trail)
+        logging.config.dictConfig(config)
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    # Handle the 'report' command
+    if args.command == "report":
+        modules = args.module or code_tags_config.modules_to_scan()
+        src = args.src or code_tags_config.source_folders_to_scan()
+        if not modules and not src:
+            print(
+                "Need to specify one or more importable modules (--module) "
+                "or source code folders/files (--src) or specify in config file.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        try:
+            found = aggregate_all_kinds_multiple_input(modules, src)
+        except ImportError:
+            print(f"Error: Could not import module(s) '{args.module}'", file=sys.stderr)
+            return 1
+
+        if args.validate:
+            if len(found["todos"]) + len(found["exceptions"]) == 0:
+                raise TypeError("No data to validate.")
+            print_validate(found)
+        else:
+            if len(found["todos"]) + len(found["exceptions"]) == 0:
+                raise TypeError("No data to report.")
+            # Call the hook.
+            results = pm.hook.code_tags_print_report(
+                format_name=args.format, output_path=args.output, found_data=found, config=get_code_tags_config()
+            )
+
+            # results = pm.hook.code_tags_print_report(format_name=args.format, found_data=found)
+            if not any(results):
+                print(f"Error: Format '{args.format}' is not supported.", file=sys.stderr)
+                return 1
+                # --- NEW: Handle 'plugin-info' command ---
+    elif args.command == "plugin-info":
+        plugin_currently_loaded(pm)
+    else:
+        # Pass control to plugins for other commands
+        # Aggregate data if plugins might need it
+        found_data_for_plugins: CollectedTODOs = {}
+        modules = []
+        src = []
+        if hasattr(args, "module") and args.module:
+            modules = getattr(args, "module", [])
+        else:
+            modules = code_tags_config.modules_to_scan()
+
+        if hasattr(args, "src") and args.src:
+            src = getattr(args, "src", [])
+        else:
+            modules = code_tags_config.source_folders_to_scan()
+
+        try:
+            # BUG: this needs to be a list
+            all_found: list[CollectedTODOs] = []
+            for source in src:
+                all_found.append(aggregate_all_kinds("", source))
+            for module in modules:
+                all_found.append(aggregate_all_kinds(module, ""))
+
+            found_data_for_plugins = merge_collected(all_found)
+        except ImportError:
+            logging.warning(f"Could not aggregate data for command {args.command}, proceeding without it.")
+            found_data_for_plugins = {"todos": [], "exceptions": []}
+
+        handled_by_plugin = pm.hook.code_tags_run_cli_command(
+            command_name=args.command, args=args, found_data=found_data_for_plugins, config=get_code_tags_config()
+        )
+        if not any(handled_by_plugin):
+            print(f"Error: Unknown command '{args.command}'.", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code_tags/aggregate.py

@@ -0,0 +1,130 @@
+"""
+Aggregate live module and source files for all known schemas
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import logging.config
+import pathlib
+
+import code_tags.folk_code_tags as folk_code_tags
+import code_tags.standard_code_tags as standard_code_tags
+from code_tags.collect import collect_all_todos
+from code_tags.collection_types import CollectedTODOs
+from code_tags.config import get_code_tags_config
+from code_tags.converters import convert_folk_tag_to_TODO, convert_pep350_tag_to_TODO
+from code_tags.plugin_manager import get_plugin_manager
+
+logger = logging.getLogger(__name__)
+
+
+def merge_collected(all_found: list[CollectedTODOs]) -> CollectedTODOs:
+    merged: CollectedTODOs = {"todos": [], "exceptions": []}
+    for found in all_found:
+        merged["todos"] += found.get("todos", [])
+        merged["exceptions"] += found.get("exceptions", [])
+    return merged
+
+
+def aggregate_all_kinds_multiple_input(module_names: list[str], source_paths: list[str]) -> CollectedTODOs:
+    """Refactor to support lists of modules and lists of source paths"""
+    if not module_names:
+        module_names = []
+    if not source_paths:
+        source_paths = []
+    collected: CollectedTODOs = {"todos": [], "exceptions": []}
+
+    for module_name in module_names:
+        found = aggregate_all_kinds(module_name, "")
+        collected["todos"] += found["todos"]
+        collected["exceptions"] += found["exceptions"]
+    for source_path in source_paths:
+        found = aggregate_all_kinds("", source_path)
+        collected["todos"] += found["todos"]
+        collected["exceptions"] += found["exceptions"]
+    return collected
+
+
+def aggregate_all_kinds(module_name: str, source_path: str) -> CollectedTODOs:
+    """
+    Aggregate all TODOs and DONEs from a module and source files.
+
+    Args:
+        module_name (str): The name of the module to search in.
+        source_path (str): The path to the source files.
+
+    Returns:
+        CollectedTODOs: A dictionary containing collected TODOs, DONEs, and exceptions.
+    """
+    config = get_code_tags_config()
+
+    active_schemas = config.active_schemas()
+    all_schemas = False
+    if not active_schemas:
+        all_schemas = True
+
+    pm = get_plugin_manager()
+    found: CollectedTODOs = {}
+    if bool(module_name):
+        logging.info(f"Checking {module_name}")
+        module = importlib.import_module(module_name)
+
+        found = collect_all_todos(module, include_submodules=False, include_exceptions=True)
+
+    found_folk_code_tags = []
+    found_pep350_code_tags = []
+
+    if source_path:
+        src_found = 0
+        path = pathlib.Path(source_path)
+        files = [path] if path.is_file() else path.rglob("*.*")
+        for file in files:
+            if file.name.endswith(".py"):
+                if all_schemas or "todo" in config.active_schemas():
+                    found_pep350_code_tags.extend(
+                        list(
+                            convert_pep350_tag_to_TODO(_)
+                            for _ in standard_code_tags.collect_pep350_code_tags(file=str(file))
+                        )
+                    )
+                    src_found += 1
+
+                if all_schemas or "folk" in config.active_schemas():
+                    found_folk_code_tags.extend(
+                        list(convert_folk_tag_to_TODO(_) for _ in folk_code_tags.find_source_tags(str(file)))
+                    )
+                    src_found += 1
+            else:
+                # Collect folk tags from plugins
+                plugin_results = pm.hook.find_source_tags(
+                    already_processed=False, file_path=str(file), config=get_code_tags_config()
+                )
+                for result_list in plugin_results:
+                    found_folk_code_tags.extend(convert_folk_tag_to_TODO(tag) for tag in result_list)
+                if plugin_results:
+                    src_found += 1
+        if src_found == 0:
+            raise TypeError(f"Can't find any files in source folder {source_path}")
+
+    folk_separated: CollectedTODOs = {"todos": found_folk_code_tags, "exceptions": []}
+    pep30_separated = {"todos": found_pep350_code_tags, "exceptions": []}
+
+    temp: CollectedTODOs = {}
+    for thing in (folk_separated, pep30_separated, found):
+        for key, value in thing.items():
+            if key not in temp:
+                # HACK: This is ugly.
+                if key == "todos":
+                    temp["todos"] = value  # type: ignore[typeddict-item]
+                else:
+                    temp["exceptions"] = value  # type: ignore[typeddict-item]
+            else:
+                if key == "todos":
+                    temp["todos"].extend(value)  # type: ignore[arg-type]
+                else:
+                    temp["exceptions"].extend(value)  # type: ignore[arg-type]
+
+    found = temp
+    return found

code_tags/collect.py

@@ -0,0 +1,271 @@
+"""
+Finds all strongly typed code tags in a module.
+
+Three ways to find strongly typed TODOs:
+
+- import module, walk the object graph. Easy to miss anything without a public interface
+- See other modules for techniques using AST parsing
+- See other modules for source parsing.
+
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+import sysconfig
+import types
+from types import ModuleType, SimpleNamespace
+from typing import Any
+
+from code_tags.collect_ast import TodoExceptionCollector
+from code_tags.collection_types import CollectedTODOs
+from code_tags.todo_tag_types import TODO, TodoException
+
+logger = logging.getLogger(__name__)
+
+
+def is_stdlib_module(module: types.ModuleType | SimpleNamespace) -> bool:
+    """
+    Check if a module is part of the Python standard library.
+
+    Args:
+        module: The module to check
+
+    Returns:
+        bool: True if the module is part of the standard library, False otherwise
+    """
+    # Built-in module (no __file__ attribute, e.g. 'sys', 'math', etc.)
+    if not hasattr(module, "__file__"):
+        return True
+
+    stdlib_path = sysconfig.get_paths()["stdlib"]
+    the_path = getattr(module, "__file__", "")
+    if not the_path:
+        return True
+    module_path = os.path.abspath(the_path)
+
+    return module_path.startswith(os.path.abspath(stdlib_path))
+
+
+class TodoCollector:
+    """Comprehensive collector for TODO, Done, and TodoException items."""
+
+    def __init__(self) -> None:
+        self.todos: list[TODO] = []
+        self.todo_exceptions: list[TodoException] = []
+        self.visited: set[int] = set()
+
+    def collect_from_module(
+        self, module: ModuleType, include_submodules: bool = True, max_depth: int = 10
+    ) -> tuple[list[TODO], list[TodoException]]:
+        """
+        Collect all TODO/Done items and TodoExceptions from a module.
+
+        Args:
+            module: The module to inspect
+            include_submodules: Whether to recursively inspect submodules
+            max_depth: Maximum recursion depth for submodules
+
+        Returns:
+            Tuple of (todos, dones, todo_exceptions)
+        """
+        self._reset()
+        self._collect_recursive(module, include_submodules, max_depth, 0)
+        return self.todos.copy(), self.todo_exceptions.copy()
+
+    def _reset(self) -> None:
+        """Reset internal collections."""
+        self.todos.clear()
+        self.todo_exceptions.clear()
+        self.visited.clear()
+
+    def _collect_recursive(self, obj: Any, include_submodules: bool, max_depth: int, current_depth: int) -> None:
+        """Recursively collect TODO/Done items from an object.
+
+        Args:
+            obj: The object to inspect
+            include_submodules: Whether to recursively inspect submodules
+            max_depth: Maximum recursion depth for submodules
+            current_depth: Current recursion depth
+        """
+        if current_depth > max_depth or id(obj) in self.visited:
+            if current_depth > max_depth:
+                logger.debug(f"Maximum depth {max_depth}")
+            else:
+                logger.debug(f"Already visited {id(obj)}")
+            return
+
+        self.visited.add(id(obj))
+
+        # Check if object itself is a TODO/Done item
+        # self._check_object_for_todos(obj)
+
+        # Handle modules
+        if inspect.ismodule(obj) and not is_stdlib_module(obj):
+            logger.debug(f"Collecting module {obj}")
+            self._collect_from_module_attributes(obj, include_submodules, max_depth, current_depth)
+
+        if isinstance(obj, SimpleNamespace):
+            logger.debug(f"Collecting namespace {obj}")
+            self._collect_from_module_attributes(obj, include_submodules, max_depth, current_depth)
+
+        # Handle classes
+        if inspect.isclass(obj):
+            logger.debug(f"Collecting class {obj}")
+            self._collect_from_class_attributes(obj, include_submodules, max_depth, current_depth)
+
+        # Handle functions and methods
+        if inspect.isfunction(obj) or inspect.ismethod(obj):
+            logger.debug(f"Collecting function/method {obj}")
+            self._check_object_for_todos(obj)
+            # Classes are showing up as functions?! Yes.
+            self._collect_from_class_attributes(obj, include_submodules, max_depth, current_depth)
+        if isinstance(obj, (list, set, tuple)) and obj:
+            logger.debug(f"Found a list/set/tuple {obj}")
+            for item in obj:
+                self._check_object_for_todos(item)
+        else:
+            # self._collect_from_class_attributes(obj, include_submodules, max_depth, current_depth)
+            logger.debug(f"Don't know what to do with {obj}")
+
+    def _check_object_for_todos(self, obj: Any) -> None:
+        """Check if an object has TODO/Done metadata."""
+        if hasattr(obj, "todo_meta"):
+            if isinstance(obj.todo_meta, TODO):
+                logger.info(f"Found todo, by instance and has todo_meta attr on {obj}")
+                self.todos.append(obj.todo_meta)
+
+    def _collect_from_module_attributes(
+        self, module: ModuleType | SimpleNamespace, include_submodules: bool, max_depth: int, current_depth: int
+    ) -> None:
+        """Collect from all attributes of a module.
+
+        Args:
+            module: The module to inspect
+            include_submodules: Whether to recursively inspect submodules
+            max_depth: Maximum recursion depth for submodules
+            current_depth: Current recursion depth
+        """
+        if is_stdlib_module(module) or module.__name__ == "builtins":
+            return
+
+        for attr_name in dir(module):
+            if attr_name.startswith("__"):
+                continue
+            # User could put a TODO on a private method and even if it isn't exported, it still is a TODO
+            # if attr_name.startswith("_"):
+            #     continue
+
+            logger.debug(f"looping : {module} : {attr_name}")
+
+            try:
+                attr = getattr(module, attr_name)
+
+                # Handle submodules
+                if include_submodules and inspect.ismodule(attr):
+                    # Avoid circular imports and built-in modules
+                    if (
+                        hasattr(attr, "__file__")
+                        and attr.__file__ is not None
+                        and not attr.__name__.startswith("builtins")
+                    ):
+                        self._collect_recursive(attr, include_submodules, max_depth, current_depth + 1)
+                # elif isinstance(list, attr) and attr:
+                #     for item in attr:
+                #         self._collect_recursive(item, include_submodules, max_depth, current_depth + 1)
+                # elif is_stdlib_module(module) or module.__name__ == "builtins":
+                #     pass
+                else:
+                    logger.debug(f"Collecting something ...{attr_name}: {attr}")
+                    self._collect_recursive(attr, include_submodules, max_depth, current_depth + 1)
+
+            except (AttributeError, ImportError, TypeError):
+                # Skip attributes that can't be accessed
+                continue
+
+    def _collect_from_class_attributes(
+        self,
+        cls: type | types.FunctionType | types.MethodType,
+        include_submodules: bool,
+        max_depth: int,
+        current_depth: int,
+    ) -> None:
+        """
+        Collect from all attributes of a class.
+
+        Args:
+            cls: The class to inspect
+            include_submodules: Whether to recursively inspect submodules
+            max_depth: Maximum recursion depth for submodules
+            current_depth: Current recursion depth
+        """
+        logger.debug("Collecting from class attributes ------------")
+        # Check class methods and attributes
+        for attr_name in dir(cls):
+            if attr_name.startswith("__"):
+                continue
+
+            try:
+                attr = getattr(cls, attr_name)
+                self._collect_recursive(attr, include_submodules, max_depth, current_depth + 1)
+            except (AttributeError, TypeError):
+                logger.error(f"ERROR ON attr_name {attr_name}")
+                continue
+
+    def collect_standalone_items(self, items_list: list[TODO]) -> tuple[list[TODO], list[TODO]]:
+        """
+        Collect standalone TODO/Done items from a list.
+
+        Args:
+            items_list: List containing TODO and Done instances
+
+        Returns:
+            Tuple of (todos, dones)
+        """
+        todos = [item for item in items_list if isinstance(item, TODO)]
+        dones = []
+        for item in todos:
+            if item.is_probably_done():
+                dones.append(item)
+                todos.remove(item)
+        return todos, dones
+
+
+def collect_all_todos(
+    module: ModuleType,
+    standalone_items: list[TODO] | None = None,
+    include_submodules: bool = True,
+    include_exceptions: bool = True,
+) -> CollectedTODOs:
+    """
+    Comprehensive collection of all TODO/Done items and exceptions.
+
+    Args:
+        module: Module to inspect
+        standalone_items: List of standalone TODO/Done items
+        include_submodules: Whether to inspect submodules
+        include_exceptions: Whether to analyze source for TodoExceptions
+
+    Returns:
+        Dictionary with 'todos', 'dones', and 'exceptions' keys
+    """
+    collector = TodoCollector()
+    # BUG: _runtime_exceptions is never really used.
+    todos, _runtime_exceptions = collector.collect_from_module(module, include_submodules)
+    logger.info(f"Found {len(todos)} TODOs in module '{module.__name__}'.")
+
+    # Collect standalone items if provided
+    if standalone_items:
+        standalone_todos, standalone_dones = collector.collect_standalone_items(standalone_items)
+        logger.info(f"Found {len(standalone_todos)} standalone TODOs and {len(standalone_dones)} standalone Dones.")
+        todos.extend(standalone_todos)
+
+    # Collect exceptions from source analysis
+    exceptions = []
+    if include_exceptions:
+        exception_collector = TodoExceptionCollector()
+        exceptions = exception_collector.collect_from_source_analysis(module)
+
+    return {"todos": todos, "exceptions": exceptions}