Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add clarification of the r string modifier #9571

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

tedsecretsource
Copy link

Raw sting literals may not be easily understood based on the brief description. This description is much more verbose (maybe too verbose) but should help the novice python programmer understand what the r modifier is and how / when to use it.

Type of Changes

Type
📜 Docs

Description

Added a more verbose description of the r (raw string literal) modifier for the novices like me…

Raw sting literals may not be easily understood based on the brief description. This description is much more verbose (maybe too verbose) but should help the novice python programmer understand what the r modifier is and how / when to use it.
Copy link
Member

@Pierre-Sassoulas Pierre-Sassoulas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for contributing to pylint and for making the doc better. I feel like this is way too verbose, It should be a sentence for each solution, maybe in a comment in the "good" example. We can add a link to a very detailed tutorial in "related.rst" however.

@Pierre-Sassoulas Pierre-Sassoulas added Documentation 📗 Skip news 🔇 This change does not require a changelog entry labels Apr 28, 2024
@UlrichEckhardt
Copy link
Contributor

I like the idea, but have some suggestions how to improve it:

  • There is a bit of inconsistent spelling, sometimes it's "Python", sometimes "python" instead.
  • I understand the issue, but if I didn't I wouldn't understand the reference to regular expressions. Make that three paragraphs, one for how escape sequences in strings work, one that explains how to use either raw strings or double backslashes and the third explaining why this is particularly useful for regular expressions.
  • "and not to modify it" -> "and not to interpret backslashes as escape characters" (Python strings are immutable already)

@tedsecretsource
Copy link
Author

Hi @Pierre-Sassoulas. Thanks for the feedback. I am brand new to this project so not sure how to add the link to related.rst. If you can provide an example, I'll give this another try.

My intention with this PR is to try and clarify, or encourage, the use of the r string modifier because, I believe, it probably should be used in the majority of cases.

How about this: Use raw string literals (prefix with 'r') or double backslashes (\\) in Python to avoid escape sequence issues in regex. Example: r"\." or "\\." for a literal dot character.

To me it's only barely better.

@UlrichEckhardt Excellent feedback. Thank you. Let's see if we can get the initial sentence right and then add details to related.rst

Looking forward to your replies.

@DanielNoord
Copy link
Collaborator

I agree that this is a bit too verbose for our documentation. We're not trying to explain all of Python, there are excellent resources for that on the internet.

@Pierre-Sassoulas
Copy link
Member

not sure how to add the link to related.rst.

Hey, you can create a file called "doc/data/messages/a/anomalous-backslash-in-string/related.rst", look at other related.rst in the repo for examples :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation 📗 Skip news 🔇 This change does not require a changelog entry Work in progress
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants