CLASPLint 0.1.0__tar.gz → 0.3.0__tar.gz

CLASPLint-0.3.0/CLASPLint/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""
+THIS FILE IS PART OF CLASPLINT BY MATT BELFAST BROWN
+CLASPLint.__init__ -- Package entry point and public API surface.
+
+Exposes the runner and reporter modules as the primary public interface for
+programmatic use of the CLASP 3.1.1 / PEP 2606 static analysis engine.
+
+Author: Matt Belfast Brown
+Create Date: 2026-06-17
+Version Date: 2026-07-01
+Version: 0.3.0
+
+THIS PROGRAM IS LICENSED UNDER GPL-3.0
+YOU SHOULD HAVE RECEIVED A COPY OF GPL-3.0 LICENSE.
+
+Copyright (C) 2026 Matt Belfast Brown
+
+CLASPLint is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, version 3 of the License.
+
+CLASPLint is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty
+of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with CLASPLint.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+# Define the package version string.
+__version__ = "0.3.0"
+# Expose the runner and reporter modules as the public API.
+__all__ = ["runner", "reporter"]

{CLASPLint-0.1.0 → CLASPLint-0.3.0}/CLASPLint/__main__.py

@@ -1,8 +1,35 @@
-# Provide the CLASPLint command-line interface entry point.
+# -*- coding: utf-8 -*-
+"""
+THIS FILE IS PART OF CLASPLINT BY MATT BELFAST BROWN
+CLASPLint.__main__ -- command-line entry point for the CLASP 3.1.1 static analysis tool.
+
+Author: Matt Belfast Brown
+Create Date: 2026-06-17
+Version Date: 2026-07-01
+Version: 0.3.0
+
+THIS PROGRAM IS LICENSED UNDER GPL-3.0
+YOU SHOULD HAVE RECEIVED A COPY OF GPL-3.0 LICENSE.
+
+Copyright (C) 2026 Matt Belfast Brown
+
+CLASPLint is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, version 3 of the License.
+
+CLASPLint is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty
+of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with CLASPLint.  If not, see <https://www.gnu.org/licenses/>.
+"""
 
 import argparse
 import sys
 import os
+from typing import Optional, Sequence
 
 from .runner import run
 from . import __version__
@@ -12,42 +39,63 @@ def _init_build_parser_function_() -> argparse.ArgumentParser:
     """Construct the argument parser for the CLASPLint CLI."""
     # Create the top-level argument parser with a description.
     parser_result = argparse.ArgumentParser(
+        # Set the program name displayed in help text.
         prog="CLASPLint",
-        description="CLASP 3.0 / PEP 2606 static analysis tool. "
+        # Provide a description of what the tool does.
+        description="CLASP 3.1.1 / PEP 2606 static analysis tool. "
+                    # Continue the description across multiple lines for readability.
                     "Checks variable, dict key, function, class naming "
+                    # Complete the tool description with comment and log conventions.
                     "and comment/log conventions.",
+    # Close the ArgumentParser constructor call.
     )
     # Accept one or more file or directory paths as positional arguments.
     parser_result.add_argument(
+        # Accept zero or more path strings as positional arguments.
         "paths", nargs="*", default=["."],
+        # Provide the help text for the paths' argument.
         help="Python files or directories to check (default: current directory).",
+    # Close the first add_argument call.
     )
     # Provide a --version flag to display the tool version.
     parser_result.add_argument(
+        # Use the version action to print the version string and exit.
         "--version", action="version",
+        # Construct the version message from the package version.
         version=f"CLASPLint {__version__}",
+    # Close the second add_argument call.
     )
     # Provide a flag to disable recursive directory traversal.
     parser_result.add_argument(
+        # Store True when --no-recursive is passed on the command line.
         "--no-recursive", action="store_true",
+        # Provide the help text for the no-recursive flag.
         help="Do not recursively check subdirectories.",
+    # Close the third add_argument call.
     )
     # Provide a quiet mode that suppresses per-violation output.
     parser_result.add_argument(
+        # Support both --quiet and -q flags for convenience.
         "--quiet", "-q", action="store_true",
+        # Provide the help text for the quiet flag.
         help="Suppress individual violation output; show only summary.",
+    # Close the fourth add_argument call.
     )
     # Provide a category filter to report only specific violation types.
     parser_result.add_argument(
+        # Accept --category or -c with a choice of violation types.
         "--category", "-c",
-        choices=["variable", "dict_key", "function", "comment", "log"],
+        # Restrict the value to the five supported violation categories.
+        choices=["variable", "dict_key", "function", "comment", "log", "docstring"],
+        # Provide the help text for the category filter.
         help="Only report violations of a specific category.",
+    # Close the fifth add_argument call.
     )
     # Return the fully configured argument parser.
     return parser_result
 
 
-def main(argv: list = None) -> int:
+def main(argv: Optional[Sequence[str]] = None) -> int:
     """Execute the CLASPLint analysis and return an exit code (0 = clean, 1 = violations)."""
     # Build and parse command-line arguments.
     parser = _init_build_parser_function_()
@@ -61,6 +109,7 @@ def main(argv: list = None) -> int:
         string_absolute = os.path.abspath(string_path)
         # Only include paths that exist on the filesystem.
         if os.path.exists(string_absolute):
+            # Add the resolved absolute path to the list.
             list_resolved.append(string_absolute)
     # Report an error if no valid paths were found.
     if not list_resolved:
@@ -76,9 +125,11 @@ def main(argv: list = None) -> int:
     if args.category:
         # Filter violations to only the requested category.
         report_result.list_violations = [
+            # Iterate over each violation to check against the filter.
             v for v in report_result.list_violations
             # Keep only violations matching the requested category filter.
             if v.string_category == args.category
+        # Close the filtered list comprehension.
         ]
     # Print the summary line to stdout.
     print(report_result.summary())