Metadata-Version: 2.4
Name: linkmedic
Version: 0.10.0
Summary: Website and open document link checker
Keywords: html,odf,xml
Author: M. Farzalipour Tabriz
License-Expression: BSD-3-Clause OR LGPL-3.0-or-later
License-File: LICENSES/BSD-3-Clause.txt
License-File: LICENSES/LGPL-3.0-or-later.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking
Project-URL: documentation, https://tbz.pages.mpcdf.de/linkmedic/
Project-URL: source, https://codeberg.org/meisam/linkmedic.git
Requires-Python: <3.15,>=3.11
Requires-Dist: beautifulsoup4>=4.13.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tomli-w>=1.2.0
Provides-Extra: odf
Requires-Dist: lxml>=5.4.0; extra == "odf"
Description-Content-Type: text/x-rst

*********
LinkMedic
*********

.. image:: https://img.shields.io/pypi/v/linkmedic
   :name: PyPI
   :target: https://pypi.org/project/linkmedic/
.. image:: https://img.shields.io/badge/Container-Quay.io-FFFFFF
   :name: Container
   :target: https://quay.io/repository/meisam/linkmedic?tab=tags
.. image:: https://img.shields.io/badge/License-BSD_3--Clause-blue
   :name: License: 3-Clause BSD
   :target: https://opensource.org/license/BSD-3-Clause
.. image:: https://img.shields.io/badge/Python-%3E=3.11-blue
   :name: Minimum supported Python version: 3.11
.. image:: https://api.reuse.software/badge/codeberg.org/meisam/linkmedic
   :name: REUSE compliance status
   :target: https://api.reuse.software/info/codeberg.org/meisam/linkmedic
.. image:: https://www.bestpractices.dev/projects/10810/badge
   :name: OpenSSF Best Practices
   :target: https://www.bestpractices.dev/en/projects/10810

.. contents::

Python package for checking internal links and resources in static web pages (``.htm``, ``.html``) and external links to HTTP(S) or FTP servers. With optional dependencies, it can also test links in OpenDocument files (``.odg``, ``.odp``, ``.ods``, ``.odt``), single OpenDocument XML files (``.fodg``, ``.fodp``, ``.fods``, ``.fodt``), and user-defined XML files.

``linkmedic`` starts a local test web server, requests the entry page from the server, and crawls all local pages. It checks all links within specific HTML/XML tags and reports any "dead" links found. If a link appears on multiple pages, it is tested only once. By default, links to external websites are ignored. If there is a ``.linkignore`` file in the website's root, links matching the regular expressions listed in this file (one pattern per line; see `user's guide <guides/USERS.rst#linkignore>`__ for examples) are also ignored during testing. After checking all the links, if any dead links are discovered, ``linkmedic`` exits with a non-zero status code.

For testing links in dynamic HTML content (e.g., using JavaScript template engines) or other document formats, you must first convert your pages (using a third-party tool) to static HTML and then run ``linkmedic`` on them.

Quick start
###########

Install prerequisites
*********************
Depending on your operating system, you may have multiple options for installing the prerequisites. For a typical installation, you will need:

* `Python interpreter <https://www.python.org/downloads/>`_: ``linkmedic`` is only tested on `officially supported Python versions <https://devguide.python.org/versions/>`_.
* A Python package installer: You can use `pip <https://pip.pypa.io/en/stable/>`_ for installing in a virtual environment or `pipx <https://pipx.pypa.io/>`_ for installing globally.

Install linkmedic
*****************
You can install ``linkmedic`` using your favorite Python package installer. For example, using ``pipx``, you can install it from `PyPI <https://pypi.org/project/linkmedic/>`__:

.. code-block:: shell

  pipx install linkmedic

Run
***
To start a test web server with files at ``/var/www`` and crawl the pages and test all the links starting from ``/var/www/index.html``, run:

.. code-block:: shell

  linkmedic --root=/var/www/

Usage
#####
Please refer to the `user's guide <guides/USERS.rst>`_ for details on the available options to install ``linkmedic`` and its usage.

Development and Maintenance
###########################
This repository is frequently used as a template for configuring Python development environments and CI/CD pipelines. It is intentionally designed with strict boundaries while prioritizing scalability and maintainability. Third-party dependencies are minimized to support this goal. The design goal is to have the option of running CI pipelines locally in an identical environment. PDM tracks exact Python dependency versions and hashes, which are detailed in its `PEP 751 lockfile <https://packaging.python.org/en/latest/specifications/pylock-toml/>`_ ``pylock.toml``.

Code coverage is intentionally not 100%. While several testing approaches are demonstrated, the focus is on showcasing practical methods rather than achieving complete coverage.

Versioning is dynamic, based on Git tags. Project documentation is versioned, and its HTML output is automatically built and deployed `here <https://tbz.pages.mpcdf.de/linkmedic/>`__.

CI and release container recipes (Dockerfiles) are versioned, with OS packages sourced from the latest minor version of their base OS image at build time.

Refer to the `developer's guide <guides/DEVELOPERS.rst>`_ for code development details, and `maintainer's guide <guides/MAINTAINERS.rst>`_ for maintenance and release.

Security and Privacy Considerations
###################################
.. danger::

   You MUST NOT run ``linkmedic`` on web pages you don't trust. This tool is designed to run inside an unprivileged, network-isolated container with only the files under test mounted as read-only. The container engine provides the primary isolation boundary against the host and other local services.

To respect user privacy, ``linkmedic`` does not send any data (e.g., telemetry, crash reports) to developers or third parties. However, when checking external links (with ``--check-external`` flag), it has to connect to other servers to verify the links, which exposes the testing machine's external IP address. This also discloses the domain name of your links to your test environment's DNS.

Reporting Issues
################
Before reporting an issue:

#. Check the `Known Issues section in the user's guide <guides/USERS.rst#known-issues>`_ for solutions to frequent problems.
#. Run ``linkmedic`` with the ``--verbose`` flag for detailed error information.

If unresolved, report bugs and code-related issues `here <https://codeberg.org/meisam/linkmedic/issues>`__. If you have an MPCDF account, use `the upstream repository <https://gitlab.mpcdf.mpg.de/tbz/linkmedic/-/issues/>`__ instead. Please include in your report relevant information such as:

* Your installation method
* Python interpreter details: ``python -c "import sys; print(sys.version)"``
* Installed packages in the environment: ``pipx list`` or ``pip freeze``
* Minimal HTML pages and the command you used to run ``linkmedic`` for reproducing the issue
* Verbose ``linkmedic`` logs

Security Issues
***************
``linkmedic`` implements defense-in-depth checks (path confinement, symlink resolution, scheme/host validation) to limit the blast radius if a file or network misconfiguration occurs within the container. However, bugs that exploits the container runtime itself should be reported to the container engine maintainers. Additionally, ``linkmedic`` doesn't use or require pre-existing secrets, so its compromise has no impact outside the container.

History
#######
The original idea for this project came from Dr. Klaus Reuter (MPCDF). Fruitful discussions with Dr. Sebastian Kehl (MPCDF) facilitated the packaging and release of this project.

Accompanying tools for ``linkmedic`` have been moved to a separate repositories:

* `linkmedkit <https://gitlab.mpcdf.mpg.de/tbz/linkmedkit>`_: starting with version 0.7
* `ndx <https://gitlab.mpcdf.mpg.de/tbz/ndx>`_: starting with version 0.10

The ``laboratory`` module has been adapted from `pre-commit-localupdate <https://gitlab.mpcdf.mpg.de/tbz/pre-commit-localupdate>`_ project.

License
#######
* Copyright 2021-2023 M. Farzalipour Tabriz, Max Planck Computing and Data Facility (MPCDF)
* Copyright 2023-2026 M. Farzalipour Tabriz, Max Planck Institute for Physics (MPP)

All rights reserved.

This software is distributed under a combination of the 3-Clause BSD License and the GNU Lesser General Public License (LGPL). The license for each individual file is specified in its header. See the `LICENSES` directory for further details.
