PyCQA / PyCQA/docformatter

I believe URL_REGEX is missing a `|`

Open
#269 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C: style P: enhancement U: low
Dominant language
Python
Stars
598
Forks
93
PR merge metrics
No merged PRs in 30d

Description

comparing the 'URL_REGEX explanation comment':

# (__ |`{{2}}|`\w[\w. :\n]*|\.\. _?[\w. :]+|')? is used to find in-line links that

to the actual first line of the regex:

    rf"(__ |`{{2}}|`\w[\w :#\n]*[.|\.\. _?[\w. :]+|')?<?"

the actual regex seems to be 'missing' a | between:

`\w[\w :#\n]*

and

[.|\.\. _?[\w. :]+

This seems to have been removed in https://github.com/PyCQA/docformatter/pull/213 , which doesn't seem intentional to me, as it doesn't seem obviously related to the change that PR was trying to fix (although it's possible I'm misunderstanding here, sorry if so!).

I think this does affect the wrapping behaviour - links in the format starting with .. seem to not get wrapped (although I'm not 100% sure I've understand the expected behaviour). A file with these contents:

def some_func():
    """This is a func.

    A description line.

    This is a very very very very very very very very very very very long line .. _a link reference:  https://domain.invalid/
    """
    pass

def another_func():
    """This is a func.

    A description line.

    .. _a link reference that is very very very very very very very very very very very very very ver longy:  https://domain.invalid/
    """
    pass

def some_func_other_link():
    """This is another func.

    This is a very very very very very very very very very very very long line `A link reference <https://domain.invalid/>`_
    """
    pass

produces this output when docformatter is run over it, only reformatting the link with a different format:

--- before/test_url_regex.py
+++ after/test_url_regex.py
@@ -19,7 +19,9 @@
 def some_func_other_link():
     """This is another func.

-    This is a very very very very very very very very very very very long line `A link reference <https://domain.invalid/>`_
+    This is a very very very very very very very very very very very
+    long line
+    `A link reference <https://domain.invalid/>`_
     """
     pass

I think maybe this isn't obvious/impactful because this kind of link is 'explicit markup' that according to ReST can only start a line of ReST, so it's probably infrequent that you get a link and reference long enough that this would reformat it anyway.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/docformatter/syntax.py by comparing the URL_REGEX explanation comment with the regex's first line, especially the alternatives around \w[\w :#\n]* and [.|\.\. _?[\w. :]+. Reproduce the wrapping behavior with the provided docstring examples, then add or update a regression test such as test_url_regex.py and confirm the expected link formatting.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.