Fix cmd options (#66)

* fix cmd options, use path_type, IntRange
* add change log and new version

Author: john0isaac

.github/workflows/devcontainer-ci.yaml

@@ -3,12 +3,12 @@ name: Check Dev Container
 on:
   workflow_dispatch:
   push:
-    branches: [ main ]
+    branches: [ main, dev ]
     paths:
       - ".devcontainer/**"
       - ".github/workflows/devcontainer-ci.yaml"
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
     paths:
       - ".devcontainer/**"
       - ".github/workflows/devcontainer-ci.yaml"

.github/workflows/python-tests.yaml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
     paths:
       - '**.py'
       - ".github/workflows/python-tests.yaml"

.github/workflows/python-types-lint-format.yaml

@@ -3,13 +3,13 @@ name: Run Python type, lint and format checks
 on:
   workflow_dispatch:
   push:
-    branches: [ main ]
+    branches: [ main, dev ]
     paths:
       - '**.py'
       - ".github/workflows/python-types-lint-format.yaml"
 
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
     paths:
       - '**.py'
       - ".github/workflows/python-types-lint-format.yaml"

.github/workflows/python-versions-tests.yaml

@@ -3,7 +3,7 @@ name: Run Python Matrix Tests
 on:
   workflow_dispatch:
   push:
-    branches: [ main ]
+    branches: [ main, dev ]
 
 permissions:
   contents: read

CHANGELOG.md

@@ -12,6 +12,9 @@ All notable changes to this project will be documented in this file.
 
 ### Other Changes
 
+## [v0.2.1] 7 Aug 2024
+- Fix command line list[str] type issue and use Click.IntRange for retries and timeout.
+
 ## [v0.2.0] 7 Aug 2024
 - Redesign the package.
 - Port to using Click instead of arg_parser.

docs/source/advanced.md

@@ -9,36 +9,47 @@ To further customize your experience with the Markdown Checker, you can utilize
 - **Description**: Path to the root directory to check.
 - **Required**: Yes
 
+### `-f`, `--func`
+- **Type**: `click.Choice`
+- **Description**: Function to be executed.
+- **Choices**:
+    - `check_broken_paths`
+    - `check_broken_urls`
+    - `check_paths_tracking`
+    - `check_urls_tracking`
+    - `check_urls_locale`
+- **Required**: Yes
+
 ### `-ext`, `--extensions`
 - **Type**: `list[str]`
 - **Description**: File extensions to filter the files.
 - **Default**: 
     - `.md`
     - `.ipynb`
-- **Required**: Yes
+- **Required**: No
 
 ### `-td`, `--tracking-domains`
 - **Type**: `list[str]`
-- **Description**: List of tracking domains to check if they have a tracking id or not.
+- **Description**: List of tracking domains to check.
 - **Default**: 
     - `github.com`
     - `microsoft.com`
     - `visualstudio.com`
     - `aka.ms`
     - `azure.com`
-- **Required**: Yes
+- **Required**: No
 
 ### `-sf`, `--skip-files`
 - **Type**: `list[str]`
 - **Description**: List of file names to skip check.
 - **Default**: 
     - `CODE_OF_CONDUCT.md`
     - `SECURITY.md`
-- **Required**: Yes
+- **Required**: No
 
 ### `-sd`, `--skip-domains`
 - **Type**: `list[str]`
-- **Description**: List of domains to skip checking if their urls are working or not.
+- **Description**: List of domains to skip checking.
 - **Default**: `[]`
 - **Required**: No
 
@@ -53,26 +64,32 @@ To further customize your experience with the Markdown Checker, you can utilize
 ### `-gu`, `--guide-url`
 - **Type**: `str`
 - **Description**: Full URL of your contributing guide.
-- **Required**: Yes
+- **Required**: No
 
 ### `-to`, `--timeout`
-- **Type**: `int`
+- **Type**: `Click.IntRange`
 - **Description**: Timeout in seconds for the requests before retrying.
 - **Default**: `10`
+- **Range**: `0-50`
 - **Required**: No
 
 ### `-rt`, `--retries`
-- **Type**: `int`
+- **Type**: `Click.IntRange`
 - **Description**: Number of retries for the requests before flagging a url as broken.
 - **Default**: `3`
+- **Range**: `0-10`
 - **Required**: No
 
 ### `-o`, `--output-file-name`
 - **Type**: `str`
 - **Description**: Name of the output file.
 - **Default**: `comment`
-- **Required**: Yes
+- **Required**: No
 
+### `SRC ...`
+- **Type**: `click.Path`
+- **Description**: Source files or directories to check.
+- **Required**: No
 
 ## Other Options
 

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "markdown-checker"
 description= "A markdown link validation reporting tool."
-version = "0.2.0"
+version = "0.2.1"
 authors = [{ name = "John Aziz", email = "[email protected]" }]
 maintainers = [{ name = "John Aziz", email = "[email protected]" }]
 license = {file = "LICENSE"}

src/markdown_checker/__init__.py

@@ -22,7 +22,9 @@
 from markdown_checker.utils.spinner import spinner
 
 
-def check_url(url: MarkdownURL, skip_domains: list[str], skip_urls_containing: list[str], timeout: int, retries: int):
+def check_url(
+    url: MarkdownURL, skip_domains: list[str], skip_urls_containing: list[str], timeout: int, retries: int
+) -> Union[None, MarkdownURL]:
     if any(url.host_name().lower() in domain.lower() for domain in skip_domains) or any(
         url.link in substring for substring in skip_urls_containing
     ):
@@ -150,44 +152,83 @@ def detect_issues(
     return detected_issues, links_count
 
 
+class ListOfStrings(click.Option):
+    """
+    Helper class to parse a list of strings from the command line.
+
+    Ref: https://stackoverflow.com/questions/47631914/how-to-pass-several-list-of-arguments-to-click-option
+    """
+
+    def type_cast_value(self, ctx, value):
+        try:
+            if isinstance(value, str):
+                # split the string by comma and remove empty strings
+                return list(filter(None, value.split(",")))
+            elif isinstance(value, list):
+                return value
+            else:
+                raise Exception
+        except Exception:
+            raise click.BadParameter(value)
+
+
 @click.command()
 @click.option(
     "-d",
     "--dir",
-    type=click.Path(exists=True, file_okay=False, dir_okay=True, readable=True),
+    type=click.Path(path_type=Path, exists=True, file_okay=False, dir_okay=True, readable=True),
     help="Path to the root directory to check.",
     required=True,
 )
+@click.option(
+    "-f",
+    "--func",
+    type=click.Choice(
+        [
+            "check_broken_paths",
+            "check_broken_urls",
+            "check_paths_tracking",
+            "check_urls_tracking",
+            "check_urls_locale",
+        ]
+    ),
+    help="Function to be executed.",
+    required=True,
+)
 @click.option(
     "-ext",
     "--extensions",
+    cls=ListOfStrings,
     type=list[str],
     default=[".md", ".ipynb"],
     help="File extensions to filter the files.",
-    required=True,
+    required=False,
 )
 @click.option(
     "-td",
     "--tracking-domains",
+    cls=ListOfStrings,
     type=list[str],
     default=["github.com", "microsoft.com", "visualstudio.com", "aka.ms", "azure.com"],
     help="List of tracking domains to check.",
-    required=True,
+    required=False,
 )
 @click.option(
     "-sf",
     "--skip-files",
+    cls=ListOfStrings,
     type=list[str],
     default=[
         "CODE_OF_CONDUCT.md",
         "SECURITY.md",
     ],
     help="List of file names to skip check.",
-    required=True,
+    required=False,
 )
 @click.option(
     "-sd",
     "--skip-domains",
+    cls=ListOfStrings,
     type=list[str],
     default=[],
     help="List of domains to skip check.",
@@ -196,45 +237,31 @@ def detect_issues(
 @click.option(
     "-suc",
     "--skip-urls-containing",
+    cls=ListOfStrings,
     type=list[str],
     default=["https://www.microsoft.com/en-us/security/blog", "video-embed.html"],
     help="List of urls to skip check.",
     required=False,
 )
-@click.option(
-    "-f",
-    "--func",
-    type=click.Choice(
-        [
-            "check_broken_paths",
-            "check_broken_urls",
-            "check_paths_tracking",
-            "check_urls_tracking",
-            "check_urls_locale",
-        ]
-    ),
-    help="Function to be executed.",
-    required=True,
-)
 @click.option(
     "-gu",
     "--guide-url",
     type=str,
     help="Full url of your contributing guide.",
-    required=True,
+    required=False,
 )
 @click.option(
     "-to",
     "--timeout",
-    type=int,
+    type=click.IntRange(0, 50),
     default=10,
     help="Timeout in seconds for the requests.",
     required=False,
 )
 @click.option(
     "-rt",
     "--retries",
-    type=int,
+    type=click.IntRange(0, 10),
     default=3,
     help="Number of retries for the requests.",
     required=False,
@@ -245,12 +272,12 @@ def detect_issues(
     type=str,
     default="comment",
     help="Name of the output file.",
-    required=True,
+    required=False,
 )
 @click.argument(
     "src",
     nargs=-1,
-    type=click.Path(exists=True, file_okay=True, dir_okay=True, readable=True),
+    type=click.Path(path_type=Path, exists=True, file_okay=True, dir_okay=True, readable=True),
     is_eager=True,
     metavar="SRC ...",
     required=False,
@@ -259,23 +286,22 @@ def detect_issues(
     message=(f"%(prog)s, %(version)s\n" f"Python ({platform.python_implementation()}) {platform.python_version()}"),
 )
 def main(
-    src: tuple[str, ...],
-    dir: str,
+    src: tuple[Path, ...],
+    dir: Path,
     func: str,
-    guide_url: str,
+    guide_url: Union[str, None],
     extensions: list[str],
     skip_files: list[str],
     skip_domains: list[str],
     skip_urls_containing: list[str],
+    tracking_domains: list[str],
     timeout: int,
     retries: int,
-    tracking_domains: list[str],
     output_file_name: str,
 ) -> None:
     """A markdown link validation reporting tool."""
-    _ = tuple(Path(item) for item in src) or (Path("./"),)  # default to current directory
-
-    _, files_paths = get_files_paths_list(Path(dir), extensions)
+    _ = src or (Path("./"),)  # default to current directory
+    _, files_paths = get_files_paths_list(dir, extensions)
 
     # remove files from skip_files list
     files_paths = [file_path for file_path in files_paths if file_path.name not in skip_files]

src/markdown_checker/reports/md_reports/generator.py

@@ -1,4 +1,5 @@
 import pathlib
+from typing import Union
 
 from markdown_checker.reports.generator_base import GeneratorBase
 
@@ -20,12 +21,14 @@ class MarkdownGenerator(GeneratorBase):
 
     def __init__(
         self,
+        contributing_guide_url: Union[str, None] = None,
         output_file_name: str = "comment",
-        contributing_guide_url: str = "https://github.com/john0isaac/markdown-checker/blob/main/CONTRIBUTING.md",
     ) -> None:
         self.output_file_name = output_file_name
         self.contributing_guide_line = (
-            f" For more details, check our [Contributing Guide]({contributing_guide_url}).\n\n"
+            (f" For more details, check our [Contributing Guide]({contributing_guide_url}).\n\n")
+            if contributing_guide_url
+            else "\n\n"
         )
 
     def _write_file(self, generated_text: str) -> None:
@@ -60,8 +63,3 @@ def generate(self, function_name: str, formatted_output: str) -> None:
         """
         generated_text = self._generate_text(function_name=function_name, formatted_output=formatted_output)
         self._write_file(generated_text)
-
-
-if __name__ == "__main__":
-    md_generator = MarkdownGenerator()
-    md_generator.generate("check_broken_paths", "This is a test")