The regex module is purposed as a replacement of standard re module. Of course we fix re bugs, but for now regex is more bugfree. Even after fixing all open re bugs, regex will remain more featured. It would be good to add a link to regex in re documentation (as there are links to other GUI libraries in Tkinter documentation).

+1

I have added the link and attached the patch below. Could you review it?

Thank you

"currently more bugfree and intended to replace re"

The first part is spreading FUD if not explained in more detail. The second is probably never going to happend :(

I have modified the patch and listed the points I know. Could you review it?

IMHO the reference proposed in the patch is too verbose. Adding details like what is supported and how to use some features I think is out of the scope of the reference. Moreover, if the regex module changes the features we are reporting in the reference, we'll have an outdated reference.

In addition, as Brett Cannon pointed out in msg287159, the preferred way to mention a 3rd-party library should be by adding the reference at the top of the page, as in Doc/library/urllib.request.rst:19.

I propose to just add a more concise reference, at the beginning of the page, like the following:

.. seealso:: regex <https://pypi.python.org/pypi/regex/>_,
a third-party alternative regular expression module.

I agree with Marco that it shouldn't be too verbose. I'd like to suggest that it says that it's compatible (i.e. has the same API), but with additional features.

Looking at the regex module and documentation, it is not clear to me whether its API behaves exactly as the re API. In addition, being a third-party module, things can change in the future.

To be defensive, IMO it is better to write as in the Ezio comment (in the review): "mostly compatible API". I propose a shorter patch, that adds the reference at the beginning of the page (right after the module introcution).

With the VERSION0 flag (the default behaviour), it should behave the same as the re module, and that's not going to change.

How about "a mostly compatible API with more thorough Unicode support"? That focuses on the VERSION1 API which is a differentiator for regex.

With the VERSION0 flag (the default behaviour), it should
behave the same as the re module, and that's not going to change.

Thanks for the clarification Matthew. However, the default version will change, as the regex PyPI page points out: "In the short term this will be VERSION0, but in the longer term it will be VERSION1." I propose a patch that integrates the Brett suggestion.

Ah, well, if it hasn't changed after this many years, it never will. Expect one or two changes to the text. :-)

How about this? Is it too long?
@matthew Barnett, I'm animalize on your repository.

.. seealso::

Third-party module `regex <https://pypi.python.org/pypi/regex>`_,

is a substitute for re module, it offers some mainstream features 
which re module lacks (Atomic grouping, Possessive quantifiers,
Variable-length lookbehind, Recursive matching). It also has further
Unicode support, some advanced grammars appears in other regular
expression engines, and many facilitations.

New changeset c8e2021 by Mariatta in branch '2.7':
bpo-22594: Add a link to the regex module in re documentation (GH-241) (GH-321)
c8e2021

New changeset 21c697f by Mariatta in branch '3.5':
bpo-22594: Add a link to the regex module in re documentation (GH-241) (GH-317)
21c697f

New changeset 1457984 by Mariatta in branch '3.6':
bpo-22594: Add a link to the regex module in re documentation (GH-241) (GH-316)
1457984

New changeset ed6795e by Mariatta (Marco Buttu) in branch 'master':
bpo-22594: Add a link to the regex module in re documentation (GH-241)
ed6795e