Merge branch 'master' into patch-1

Author: hukkin

.github/workflows/tests.yaml

@@ -16,11 +16,11 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v3
       with:
-        python-version: '3.8'
+        python-version: '3.11'
 
     - name: Installation (deps and package)
       run: |
-        pip install . pre-commit mypy==0.910 -r tests/requirements.txt
+        pip install . pre-commit mypy==1.11.2 -r tests/requirements.txt
 
     - name: run linters
       run: |
@@ -33,9 +33,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12-dev']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13-dev']
         os: [ubuntu-latest, macos-latest, windows-latest]
-    continue-on-error: ${{ matrix.python-version == '3.12-dev' }}
+    continue-on-error: ${{ matrix.python-version == '3.13-dev' }}
 
     steps:
     - uses: actions/checkout@v3
@@ -51,10 +51,10 @@ jobs:
 
     - name: Test with pytest
       run: |
-        pytest --cov --cov-fail-under=100
+        pytest --cov
 
     - name: Report coverage
-      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8'
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
       uses: codecov/codecov-action@v2
 
   allgood:
@@ -74,7 +74,7 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v3
       with:
-        python-version: '3.8'
+        python-version: '3.x'
     - name: Install build and publish tools
       run: |
         pip install build twine

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: f71fa2c1f9cf5cb705f73dffe4b21f7c61470ba9  # frozen: v4.4.0
+  rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b  # frozen: v5.0.0
   hooks:
   - id: check-yaml
   - id: check-toml
@@ -23,22 +23,26 @@ repos:
   hooks:
   - id: absolufy-imports
 - repo: https://github.com/PyCQA/isort
-  rev: dbf82f2dd09ae41d9355bcd7ab69187a19e6bf2f  # frozen: 5.12.0
+  rev: c235f5e450b4b84e58d114ed4c589cbf454175a3  # frozen: 5.13.2
   hooks:
   - id: isort
 - repo: https://github.com/psf/black
-  rev: 193ee766ca496871f93621d6b58d57a6564ff81b  # frozen: 23.7.0
+  rev: 1b2427a2b785cc4aac97c19bb4b9a0de063f9547  # frozen: 24.10.0
   hooks:
   - id: black
-- repo: https://github.com/myint/docformatter
-  rev: dfefe062799848234b4cd60b04aa633c0608025e  # frozen: v1.7.5
+- repo: https://github.com/hukkin/docformatter
+  rev: ab802050e6e96aaaf7f917fcbc333bb74e2e57f7  # frozen: v1.4.2
   hooks:
   - id: docformatter
 - repo: https://github.com/PyCQA/flake8
-  rev: 10f4af6dbcf93456ba7df762278ae61ba3120dc6  # frozen: 6.1.0
+  rev: e43806be3607110919eff72939fda031776e885a  # frozen: 7.1.1
   hooks:
   - id: flake8
     additional_dependencies:
     - flake8-bugbear
     - flake8-builtins
     - flake8-comprehensions
+- repo: https://github.com/pre-commit/pre-commit
+  rev: cc4a52241565440ce200666799eef70626457488  # frozen: v4.0.1
+  hooks:
+  - id: validate_manifest

README.md

@@ -41,7 +41,7 @@ Note that GitHub's Markdown renderer supports syntax extensions not included in
 For full GitHub support do:
 
 ```bash
-pip install mdformat-gfm mdformat-frontmatter mdformat-footnote
+pip install mdformat-gfm mdformat-frontmatter mdformat-footnote mdformat-gfm-alerts
 ```
 
 Install with [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) support:
@@ -90,7 +90,9 @@ If a file is not properly formatted, the exit code will be non-zero.
 
 ```console
 foo@bar:~$ mdformat --help
-usage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}] [paths ...]
+usage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}]
+                [--end-of-line {lf,crlf,keep}] [--exclude PATTERN]
+                [paths ...]
 
 CommonMark compliant Markdown formatter
 
@@ -106,8 +108,11 @@ options:
                         paragraph word wrap mode (default: keep)
   --end-of-line {lf,crlf,keep}
                         output file line ending mode (default: lf)
+  --exclude PATTERN     exclude files that match the Unix-style glob pattern (multiple allowed)
 ```
 
+The `--exclude` option is only available on Python 3.13+.
+
 <!-- end cli-usage -->
 
 ## Documentation

docs/contributors/contributing.md

@@ -60,11 +60,11 @@ setuptools.setup(
 )
 ```
 
-If using Poetry for packaging, the entry point configuration in `pyproject.toml` would need to be like:
+If using a PEP 621 compliant build backend (e.g. Flit) for packaging, the entry point configuration in `pyproject.toml` would need to be like:
 
 ```toml
 # other config here...
-[tool.poetry.plugins."mdformat.codeformatter"]
+[project.entry-points."mdformat.codeformatter"]
 "python" = "my_package.some_module:format_python"
 ```
 
@@ -112,10 +112,17 @@ setuptools.setup(
 If using Poetry or Flit for packaging, the entry point configuration in `pyproject.toml` would need to be like:
 
 ```toml
-# other config here...
+# Poetry specific:
 [tool.poetry.plugins."mdformat.parser_extension"]
 "myextension" = "my_package:ext_module_or_class"
-# or
-[tool.flit.plugins."mdformat.parser_extension"]
+```
+
+```toml
+# or PEP 621 compliant (works with Flit):
+[project.entry-points."mdformat.parser_extension"]
 "myextension" = "my_package:ext_module_or_class"
 ```
+
+## Making your plugin discoverable
+
+In case you host your plugin on GitHub, make sure to add it under the "mdformat" topic so it shows up on https://github.com/topics/mdformat.

docs/requirements.txt

@@ -1,6 +1,6 @@
 # List dependencies in a format that readthedocs.org understands.
 
-docutils == 0.18.1
-sphinx == 5.1.1
-myst-parser == 0.18.0
-furo == 2022.6.21
+docutils == 0.21.2
+sphinx == 8.0.2
+myst-parser == 4.0.0
+furo == 2024.8.6

docs/users/configuration_file.md

@@ -20,4 +20,34 @@ Command line interface arguments take precedence over the configuration file.
 wrap = "keep"       # possible values: {"keep", "no", INTEGER}
 number = false      # possible values: {false, true}
 end_of_line = "lf"  # possible values: {"lf", "crlf", "keep"}
+
+# Python 3.13+ only:
+exclude = []        # possible values: a list of file path pattern strings
+```
+
+## Exclude patterns
+
+A list of file exclusion patterns can be defined on Python 3.13+.
+Unix-style glob patterns are supported, see
+[Python's documentation](https://docs.python.org/3/library/pathlib.html#pattern-language)
+for syntax definition.
+
+Glob patterns are matched against relative paths.
+If `--exclude` is used on the command line, the paths are relative to current working directory.
+Else the paths are relative to the parent directory of the file's `.mdformat.toml`.
+
+Files that match an exclusion pattern are _always_ excluded,
+even in the case that they are directly referenced in a command line invocation.
+
+### Example patterns
+
+```toml
+# .mdformat.toml
+exclude = [
+    "CHANGELOG.md",              # exclude a single root level file
+    "venv/**",                   # recursively exclude a root level directory
+    "**/node_modules/**",        # recursively exclude a directory at any level
+    "**/*.txt",                  # exclude all .txt files
+    "**/*.m[!d]", "**/*.[!m]d",  # exclude all files that are not suffixed .md
+]
 ```

docs/users/plugins.md

@@ -23,7 +23,7 @@ formatted = mdformat.text(unformatted, codeformatters={"python"})
 assert formatted == '```python\n"""black converts quotes"""\n```\n'
 ````
 
-### Existing plugins
+### Existing plugins (see https://github.com/topics/mdformat for more!)
 
 <table>
   <tr>
@@ -51,6 +51,11 @@ assert formatted == '```python\n"""black converts quotes"""\n```\n'
     <td><code>go</code></td>
     <td>Requires <a href="https://golang.org/doc/install">Go</a> installation</td>
   </tr>
+  <tr>
+    <td><a href="https://github.com/Freed-Wu/mdformat-ruff">mdformat-ruff</a></td>
+    <td><code>python</code></td>
+    <td></td>
+  </tr>
   <tr>
     <td><a href="https://github.com/hukkin/mdformat-rustfmt">mdformat-rustfmt</a></td>
     <td><code>rust</code></td>
@@ -85,7 +90,7 @@ unformatted = "content...\n"
 formatted = mdformat.text(unformatted, extensions={"tables"})
 ```
 
-### Existing plugins
+### Existing plugins (see https://github.com/topics/mdformat for more!)
 
 <table>
   <tr>
@@ -118,6 +123,11 @@ formatted = mdformat.text(unformatted, extensions={"tables"})
     <td><code>gfm</code></td>
     <td>Changes target specification to GitHub Flavored Markdown (GFM)</td>
   </tr>
+  <tr>
+    <td><a href="https://github.com/KyleKing/mdformat-gfm-alerts">mdformat-gfm-alerts</a></td>
+    <td><code>gfm_alerts</code></td>
+    <td>Extends GitHub Flavored Markdown (GFM) with "Alerts"</td>
+  </tr>
   <tr>
     <td><a href="https://github.com/KyleKing/mdformat-mkdocs">mdformat-mkdocs</a></td>
     <td><code>mkdocs</code></td>

pyproject.toml

@@ -11,7 +11,7 @@ authors = [
     { name = "Taneli Hukkinen", email = "[email protected]" },
 ]
 license = { file = "LICENSE" }
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = [
     'markdown-it-py >=1.0.0,<4.0.0',
     'tomli >=1.1.0; python_version < "3.11"',
@@ -63,15 +63,15 @@ xfail_strict = true
 legacy_tox_ini = '''
 [tox]
 # Only run pytest envs when no args given to tox
-envlist = py{38,39,310,311}
+envlist = py{39,310,311,312,313}
 isolated_build = True
 
-[testenv:py{38,39,310,311}]
+[testenv:py{39,310,311,312,313}]
 description = run tests
 deps =
     -r tests/requirements.txt
 commands =
-    pytest {posargs}
+    pytest {posargs:--cov}
 
 [testenv:profile]
 description = run profiler (use e.g. `firefox .tox/prof/combined.svg` to open)
@@ -90,10 +90,10 @@ commands = pre-commit run {posargs:--all}
 
 [testenv:mypy]
 description = run mypy
-basepython = python3.8
+basepython = python3.11
 deps =
     -r tests/requirements.txt
-    mypy==0.910
+    mypy==1.11.2
 commands =
     mypy {posargs:src/ tests/}
 
@@ -135,20 +135,7 @@ commands =
 
 [tool.coverage.run]
 source = ["mdformat"]
-omit = ["*/__main__.py"]
-
-[tool.coverage.report]
-# Regexes for lines to exclude from consideration
-exclude_lines = [
-    # Re-enable the standard pragma (with extra strictness)
-    '# pragma: no cover\b',
-    # Ellipsis lines after @typing.overload
-    '^ +\.\.\.$',
-    # Code for static type checkers
-    "if TYPE_CHECKING:",
-    # Scripts
-    'if __name__ == .__main__.:',
-]
+plugins = ["covdefaults"]
 
 
 [tool.mypy]
@@ -168,8 +155,3 @@ no_implicit_optional = true
 [[tool.mypy.overrides]]
 module = "tests.*"
 disallow_untyped_defs = false
-
-[[tool.mypy.overrides]]
-# This matches `fuzzer/fuzz.py`.
-module = "fuzz"
-ignore_errors = true