Markdown-Checker 1.0.2__tar.gz → 1.0.3__tar.gz

{markdown_checker-1.0.2/src/markdown_checker.egg-info → markdown_checker-1.0.3}/PKG-INFO

@@ -1,39 +1,14 @@
 Metadata-Version: 2.4
 Name: markdown-checker
-Version: 1.0.2
+Version: 1.0.3
 Summary: A markdown link validation reporting tool.
 Author-email: John Aziz <johnaziz269@gmail.com>
 Maintainer-email: John Aziz <johnaziz269@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2023 John Aziz
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Project-URL: Homepage, https://github.com/john0isaac/markdown-checker
-Project-URL: Documentation, https://markdown-checker.readthedocs.io/en/latest/
-Project-URL: Issues, https://github.com/john0isaac/markdown-checker/issues
-Project-URL: Contributing, https://github.com/john0isaac/markdown-checker/pulls
-Project-URL: Releases, https://github.com/john0isaac/markdown-checker/releases
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-Expression: MIT
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -41,27 +16,17 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: click>=8.3.3
-Requires-Dist: httpx>=0.28.1
-Provides-Extra: dev
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Provides-Extra: lint
-Requires-Dist: ruff; extra == "lint"
-Provides-Extra: test
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-cov; extra == "test"
-Provides-Extra: docs
-Requires-Dist: mkdocs; extra == "docs"
-Requires-Dist: mkdocs-material; extra == "docs"
-Requires-Dist: mkdocstrings[python]; extra == "docs"
-Requires-Dist: pymdown-extensions; extra == "docs"
-Dynamic: license-file
+Requires-Dist: click>=8.3.1
+Requires-Dist: httpx2>=2.0.0
+Project-URL: Contributing, https://github.com/john0isaac/markdown-checker/pulls
+Project-URL: Documentation, https://markdown-checker.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/john0isaac/markdown-checker
+Project-URL: Issues, https://github.com/john0isaac/markdown-checker/issues
+Project-URL: Releases, https://github.com/john0isaac/markdown-checker/releases
 
 [![PyPi](https://img.shields.io/pypi/v/markdown-checker)](https://pypi.org/project/markdown-checker/)
 [![Documentation Status](https://readthedocs.org/projects/markdown-checker/badge/?version=latest)](https://markdown-checker.readthedocs.io/en/latest/?badge=latest)
@@ -160,3 +125,4 @@ Example:
 ```bash
 markdown-checker -d . -f check_urls_tracking -gu https://github.com/john0isaac/markdown-checker/blob/main/CONTRIBUTING.md
 ```
+

markdown_checker-1.0.3/docs/CODE_OF_CONDUCT.rst

@@ -0,0 +1,138 @@
+Contributor Covenant Code of Conduct
+====================================
+
+Our Pledge
+----------
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Enforcement Responsibilities
+----------------------------
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+Scope
+-----
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail
+address, posting via an official social media account, or acting as an
+appointed representative at an online or offline event.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+johnaziz269@gmail.com. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+Enforcement Guidelines
+----------------------
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct.
+
+1. Correction
+~~~~~~~~~~~~~
+
+**Community Impact:** Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence:** A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+2. Warning
+~~~~~~~~~~
+
+**Community Impact:** A violation through a single incident or series of
+actions.
+
+**Consequence:** A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+3. Temporary Ban
+~~~~~~~~~~~~~~~~
+
+**Community Impact:** A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+4. Permanent Ban
+~~~~~~~~~~~~~~~~
+
+**Community Impact:** Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within the
+community.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the
+`Contributor Covenant <https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>`_,
+version 2.0.
+
+Community Impact Guidelines were inspired by the
+`Mozilla code of conduct enforcement ladder <https://github.com/mozilla/diversity>`_.
+
+For answers to common questions about this code of conduct, see the
+`FAQ <https://www.contributor-covenant.org/faq>`_. Translations are available
+at `https://www.contributor-covenant.org/translations <https://www.contributor-covenant.org/translations>`_.

markdown_checker-1.0.3/docs/CONTRIBUTING.rst

@@ -0,0 +1,60 @@
+Contribution
+============
+
+How to `contribute to the project <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_?
+
+While contributing, each contributor should keep the
+:doc:`Code of Conduct <CODE_OF_CONDUCT>` in mind.
+
+This repository is open for everyone to contribute and is maintained by
+`John Aziz <https://github.com/john0isaac>`_.
+
+Develop Locally
+---------------
+
+Install all dependencies and the package in editable mode:
+
+.. code-block:: shell
+
+	 uv sync
+
+Activate the virtual environment:
+
+.. code-block:: shell
+
+	 source .venv/bin/activate
+
+Any changes you make to the source will take effect immediately.
+
+First Steps
+-----------
+
+These are the most common commands you will use:
+
+- ``pytest``: Run the unit tests.
+- ``mypy``: Run the type checker.
+- ``ruff``: Run the linter and formatter tools.
+- ``tox run -e docs``: Build the documentation.
+
+These are some more specific commands if you need them:
+
+- ``tox parallel``: Run all test environments that will be run in CI, in
+	parallel. Python versions that are not installed are skipped.
+- ``pre-commit``: Run the linter and formatter tools. Only staged files are
+	checked, and this runs automatically before each commit.
+- ``pre-commit run --all-files``: Run the pre-commit hooks against all files,
+	including unchanged and unstaged files.
+- ``tox run -e py3.11``: Run unit tests with a specific Python version. The
+	version must be installed.
+- ``tox run -e style``: Run all pre-commit hooks on all files via tox.
+- ``tox run -e typing``: Run all typing checks.
+- ``tox run -e docs``: Build the documentation in strict mode.
+- ``tox run -e docs-auto``: Serve the documentation locally with auto-reload.
+- ``tox run -e update-actions``: Update GitHub Actions pins.
+- ``tox run -e update-pre_commit``: Update pre-commit hook pins.
+- ``tox run -e update-requirements``: Update the ``uv.lock`` file.
+
+.. tip::
+
+	 ``tox run`` and ``tox parallel`` can be shortened to ``tox r`` and
+	 ``tox p``.

markdown_checker-1.0.3/docs/advanced.rst

@@ -0,0 +1,388 @@
+Advanced Usage
+==============
+
+To further customize your experience with Markdown Checker, you can use
+additional command-line interface options.
+
+.. contents:: On this page
+  :local:
+
+Working with List Parameters
+----------------------------
+
+Several CLI options accept lists of values, including ``--skip-domains``,
+``--skip-files``, ``--extensions``, ``--tracking-domains``, and
+``--skip-urls-containing``.
+
+How to provide multiple values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use comma-separated values without spaces:
+
+.. code-block:: bash
+
+  markdown-checker -d . -f check_broken_urls --skip-domains=example.com,test.com
+
+Important formatting rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Values must be separated by commas with no spaces.
+- Do not use square brackets.
+- Do not add spaces after commas.
+- Quotes are optional but not required.
+
+Examples of correct and incorrect usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Wrong: ``--skip-domains=[example.com,test.com]``. Square brackets are not
+  allowed.
+- Wrong: ``--skip-domains=example.com, test.com``. Spaces are not allowed.
+- Wrong: ``--skip-domains example.com test.com``. Use ``=`` and commas.
+- Correct: ``--skip-domains=example.com,test.com``.
+- Correct: ``--skip-domains="example.com,test.com"``. Quotes are optional.
+
+Command Line Options
+--------------------
+
+``SRC ...``
+~~~~~~~~~~~
+
+Type
+  ``click.Path``
+Description
+  Source files or directories to check.
+Required
+  No. Either ``SRC`` or ``--dir`` must be provided.
+
+``-d``, ``--dir``
+~~~~~~~~~~~~~~~~~
+
+Type
+  ``click.Path``
+Description
+  Path to the root directory to check.
+Required
+  No. Either ``SRC`` or ``--dir`` must be provided.
+
+``-f``, ``--func``
+~~~~~~~~~~~~~~~~~~
+
+Type
+  ``click.Choice``
+Description
+  Function to execute.
+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 used to filter the files.
+Default
+  ``.md``, ``.ipynb``
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Single value
+  markdown-checker -d . -f check_broken_paths --extensions=.md
+
+  # Multiple values (comma-separated, no spaces)
+  markdown-checker -d . -f check_broken_paths --extensions=.md,.ipynb,.txt
+
+``-td``, ``--tracking-domains``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``list[str]``
+Description
+  List of tracking domains to check.
+Default
+  ``github.com``, ``microsoft.com``, ``visualstudio.com``, ``aka.ms``,
+  ``azure.com``
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Single value
+  markdown-checker -d . -f check_urls_tracking --tracking-domains=github.com
+
+  # Multiple values (comma-separated, no spaces)
+  markdown-checker -d . -f check_urls_tracking --tracking-domains=github.com,microsoft.com
+
+``-sf``, ``--skip-files``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``list[str]``
+Description
+  List of file names to skip.
+Default
+  ``CODE_OF_CONDUCT.md``, ``SECURITY.md``
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Single value
+  markdown-checker -d . -f check_broken_paths --skip-files=README.md
+
+  # Multiple values (comma-separated, no spaces)
+  markdown-checker -d . -f check_broken_paths --skip-files=README.md,CHANGELOG.md,LICENSE.md
+
+``-sd``, ``--skip-domains``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``list[str]``
+Description
+  List of domains to skip during checking.
+Default
+  ``[]``
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Single value
+  markdown-checker -d . -f check_broken_urls --skip-domains=example.com
+
+  # Multiple values (comma-separated, no spaces)
+  markdown-checker -d . -f check_broken_urls --skip-domains=example.com,test.com
+
+``-suc``, ``--skip-urls-containing``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``list[str]``
+Description
+  List of URL substrings to skip.
+Default
+  ``[]``
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Single value
+  markdown-checker -d . -f check_broken_urls --skip-urls-containing=/embed/
+
+  # Multiple values (comma-separated, no spaces)
+  markdown-checker -d . -f check_broken_urls --skip-urls-containing=/embed/,/preview/,video-embed.html
+
+``-gu``, ``--guide-url``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``str``
+Description
+  Full URL of your contributing guide.
+Required
+  No.
+
+``-to``, ``--timeout``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``Click.IntRange``
+Description
+  Timeout in seconds for requests before retrying.
+Default
+  ``20``
+Range
+  ``0-50``
+Required
+  No.
+
+``-rt``, ``--retries``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``Click.IntRange``
+Description
+  Number of retries before flagging a URL as broken.
+Default
+  ``3``
+Range
+  ``0-10``
+Required
+  No.
+
+``--retry-on-429`` / ``--no-retry-on-429``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``bool``
+Description
+  When enabled, the checker honours the ``Retry-After`` response header on
+  ``429 Too Many Requests`` (and any other non-success, non-redirect response
+  that carries the header). The indicated wait time is used instead of the
+  normal exponential backoff. Disable with ``--no-retry-on-429`` to fall back
+  to standard retry behaviour.
+Default
+  Enabled (``--retry-on-429``)
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Enabled (default)
+  markdown-checker -d . -f check_broken_urls --retry-on-429
+
+  # Disabled
+  markdown-checker -d . -f check_broken_urls --no-retry-on-429
+
+``-frd``, ``--fallback-retry-delay``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``Click.IntRange``
+Description
+  Number of seconds to wait before retrying when a ``429`` response is
+  received but carries no ``Retry-After`` header. Only applies when
+  ``--retry-on-429`` is enabled.
+Default
+  ``30``
+Range
+  ``0-300``
+Required
+  No.
+
+Usage examples
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  # Use a custom fallback delay of 45 seconds
+  markdown-checker -d . -f check_broken_urls --fallback-retry-delay=45
+
+  # Short-form alias
+  markdown-checker -d . -f check_broken_urls -frd 45
+
+``-o``, ``--output-file-name``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type
+  ``str``
+Description
+  Name of the output file.
+Default
+  ``comment``
+Required
+  No.
+
+URL Check Outcomes
+------------------
+
+When ``check_broken_urls`` runs, each URL is evaluated by
+``MarkdownURL.check()``, which returns a ``URLCheckResult`` with one of five
+statuses.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Status
+     - Meaning
+   * - ``alive``
+     - A ``2xx`` HTTP response was received. The link is healthy.
+   * - ``broken``
+     - All retries returned non-``2xx`` responses (e.g. ``404 Not Found``).
+       The link is reported as an issue.
+   * - ``rate_limited``
+     - No hard HTTP failure was observed, and at least one retry encountered
+       ``429 Too Many Requests`` (with or without a ``Retry-After`` header).
+       The link is reported as a **warning-level issue**
+       (``issue_level="warning"``). It does not cause the CLI to exit with a
+       non-zero code.
+   * - ``transient_error``
+     - No hard HTTP failure or rate-limit response was observed, and the
+       attempts failed with network-level exceptions (e.g. DNS failure,
+       connection timeout). The link is reported as a **warning-level issue**
+       and does not cause the CLI to exit with a non-zero code.
+   * - ``unverifiable``
+     - Both HEAD and GET returned ``401 Unauthorized`` or ``403 Forbidden``.
+       The server is reachable but is blocking automated access (e.g.
+       Cloudflare bot protection). The real status of the resource cannot be
+       determined. The link is reported as a **warning-level issue** and does
+       not cause the CLI to exit with a non-zero code.
+
+Rate limiting and access errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When one or more URLs are rate-limited, unverifiable, or cannot be reached due
+to transient network failures, the CLI prints a yellow warning summary followed
+by one warning line per affected link, after the error-level issues (if any).
+
+In local mode::
+
+  🔍 Checked 42 links in 10 files.
+  ⚠ 3 links had warnings:
+  	File '/path/to/file.md', line 12
+  https://example.com/api was skipped due to rate limiting.
+
+  	File '/path/to/file.md', line 15
+  https://stackoverflow.com/a/123 could not be verified (access was forbidden by the server).
+
+In CI mode (``$CI=true``), GitHub Actions ``::warning::`` annotations are
+emitted instead::
+
+  🔍 Checked 42 links in 10 files.
+  ::warning file=path/to/file.md,line=12::File path/to/file.md, line 12, Link https://example.com/api was skipped due to rate limiting.
+  ::warning file=path/to/file.md,line=15::File path/to/file.md, line 15, Link https://stackoverflow.com/a/123 could not be verified (access was forbidden by the server).
+
+Warning-level issues do **not** cause the CLI to exit with a non-zero code.
+Only error-level issues (broken links) cause a non-zero exit.
+
+If a run mixes rate-limited responses with transient network failures, the
+outcome is reported as ``rate_limited`` unless a hard HTTP failure is also
+observed. Any hard HTTP failure causes the final outcome to be ``broken``.
+
+Other Options
+-------------
+
+``--version``
+~~~~~~~~~~~~~
+
+Type
+  ``bool``
+Description
+  Show the version and exit.
+Required
+  No.
+
+``--help``
+~~~~~~~~~~
+
+Type
+  ``bool``
+Description
+  Show the help message and exit.
+Required
+  No.

markdown_checker-1.0.3/docs/api/checker.rst

@@ -0,0 +1,7 @@
+Checker
+=======
+
+.. automodule:: markdown_checker.checker
+	:members:
+	:undoc-members:
+	:show-inheritance: