Improved docs

README.md

@@ -38,7 +38,7 @@ main.py:16:9 [FURB105]: Use `print() instead of `print("")`
 Before installing, it is recommended that you setup a [virtual environment](https://docs.python.org/3/tutorial/venv.html).
 
 ```
-$ pip3 install refurb
+$ pip install refurb
 $ refurb file.py folder/
 ```
 
@@ -253,7 +253,7 @@ let `pre-commit` find the most recent one for you).
 Installing plugins for Refurb is very easy:
 
 ```
-$ pip3 install refurb-plugin-example
+$ pip install refurb-plugin-example
 ```
 
 Where `refurb-plugin-example` is the name of the plugin. Refurb will automatically load

docs/check-ideas.md

@@ -5,7 +5,7 @@ be picked up by anyone looking to add new checks to Refurb!
 
 ## Pathlib
 
-### Dont use `+` for path traversal, use `/` operator
+### Don't use `+` for path traversal, use `/` operator
 
 Bad:
 
@@ -33,9 +33,9 @@ These should be opt-in, since they can be quite noisy.
   - Include `dict`, `set`, `frozenset`, `defaultdict`, etc
   - See `TypeApplication` Mypy node
 
-* Convert `Optional[x]` -> `x | None` (python 3.9+?)
+* Convert `Optional[x]` -> `x | None` (python 3.10+)
 
-* Convert `Union[x, y]` -> `x | y` (python 3.9+)
+* Convert `Union[x, y]` -> `x | y` (python 3.10+)
 
 ## Dataclasses
 
@@ -66,19 +66,11 @@ class Person:
 
 ## String
 
-### Use fstring instead of `+`
+### Use f-string instead of `+`
 
 Disable by default, will be noisy
 
-### Dont hard code charsets (ie, `string.digits` vs `"0123456789"`)
-
-Python has many built-in charsets in the [string](https://docs.python.org/3/library/string.html) library, and can be used instead of defining them yourself.
-
-We probably only want to check this in `in` expressions, since `x in "abc"` returns the same thing
-as `x in "cba"`, but `x == "abc"[0]` and `x == "cba"[0]` do not. Perhaps there should be a flag for
-detecting any strings which contains a (permutated) version of a built-in charset.
-
-### Dont use `" ".join(x.capitalize() for x in s.split())`, use `string.capwords(x)`
+### Don't use `" ".join(x.capitalize() for x in s.split())`, use `string.capwords(x)`
 
 Notes:
 
@@ -146,13 +138,13 @@ See https://docs.python.org/3/library/stdtypes.html
 See https://docs.python.org/3/library/io.html
 
 * Use `frozenset` when `set` is never appended to
-* Dont roll your own max/min/sum functions, use `max`/`min`/`sum` instead
+* Don't roll your own max/min/sum functions, use `max`/`min`/`sum` instead
 * `print(f"{x} {y}")` -> `print(x, y)`
-* Dont use `_` in expressions
+* Don't use `_` in expressions
 * Use `x ** y` instead of `pow(x, y)`
   * Unless the `mod` param of `pow` is being used
-* Dont call `print()` repeatedly, call `print()` once with multi line string
-* Dont call `sys.stderr.write("asdf\n")`, use `print("asdf", file=sys.stderr)`
+* Don't call `print()` repeatedly, call `print()` once with multi line string
+* Don't call `sys.stderr.write("asdf\n")`, use `print("asdf", file=sys.stderr)`
 
 ## Enum
 
@@ -197,4 +189,4 @@ for item in itertools.chain(list1, list2, list3):
 
 ## Iteration
 
-### Dont use `x = x[::-1]`, use `x.reverse()`
+### Don't use `x = x[::-1]`, use `x.reverse()`

docs/checks.md

@@ -6,7 +6,7 @@ Categories: `pathlib`
 
 A common operation is changing the extension of a file. If you have an
 existing `Path` object, you don't need to convert it to a string, slice
-it, and append a new extension. Instead, use the `with_suffix()` function:
+it, and append a new extension. Instead, use the `with_suffix()` method:
 
 Bad:
 
@@ -45,7 +45,7 @@ contents = Path(filename).read_text()
 
 Categories: `string`
 
-`startswith()` and `endswith()` both takes a tuple, so instead of calling
+`startswith()` and `endswith()` both take a tuple, so instead of calling
 `startswith()` multiple times on the same string, you can check them all
 at once:
 
@@ -70,7 +70,7 @@ if name.startswith(("b", "B")):
 Categories: `pathlib`
 
 When you just want to save some contents to a file, using a `with` block is
-a bit overkill. Instead you can use pathlib's `write_text()` function:
+a bit overkill. Instead you can use pathlib's `write_text()` method:
 
 Bad:
 
@@ -89,7 +89,7 @@ Path(filename).write_text("hello world")
 
 Categories: `pathlib`
 
-A modern alternative to `os.getcwd()` is the `Path.cwd()` function:
+A modern alternative to `os.getcwd()` is the `Path.cwd()` method:
 
 Bad:
 
@@ -139,7 +139,7 @@ Categories: `contextlib` `readability`
 Often times you want to handle an exception, and just ignore it. You can do
 this with a `try/except` block, using a single `pass` in the `except`
 block, but there is a simpler and more concise way using the `suppress()`
-method from `contextlib`:
+function from `contextlib`:
 
 Bad:
 
@@ -162,8 +162,8 @@ with suppress(FileNotFoundError):
 
 Categories: `logical` `readability`
 
-When comparing a value to multiple possible options, don't use multiple
-`or` checks, use a single `in` expr:
+When comparing a value to multiple possible options, don't `or` multiple
+comparison checks, use a single `in` expr:
 
 Bad:
 
@@ -193,7 +193,7 @@ is best to pick one and stick with it.
 Bad:
 
 ```python
-for x in [1, 2, 3]:
+for x in (1, 2, 3):
     pass
 
 nums = [str(x) for x in [1, 2, 3]]
@@ -212,8 +212,8 @@ nums = [str(x) for x in (1, 2, 3)]
 
 Categories: `logical` `readability`
 
-Sometimes ternary (aka, inline if statements) can be simplified to a single
-`or` expression.
+Sometimes the ternary operator (aka, inline if statements) can be simplified to
+a single `or` expression.
 
 Bad:
 
@@ -357,7 +357,7 @@ Categories: `builtin` `fstring`
 The `bin()`, `oct()`, and `hex()` functions return the string
 representation of a number but with a prefix attached. If you don't want
 the prefix, you might be tempted to just slice it off, but using an
-f-string will give you more flexibility:
+f-string will give you more flexibility and let you work with negative numbers:
 
 Bad:
 
@@ -944,7 +944,7 @@ for book in books.values():
 Categories: `builtin` `logical` `readability`
 
 Certain ternary expressions can be written more succinctly using the
-builtin `max()` function:
+builtin `min`/`max` functions:
 
 Bad:
 
@@ -968,9 +968,9 @@ highest_score = max(score1, score2)
 
 Categories: `builtin` `iterable` `readability`
 
-Often times generator and comprehension expressions can be written more
-succinctly. For example, passing a list comprehension to a function when
-a generator expression would suffice, or using the shorthand notation
+Often times generator expressions and list/set/dict comprehensions can be
+written more succinctly. For example, passing a list comprehension to a function
+when a generator expression would suffice, or using the shorthand notation
 in the case of `list` and `set`. For example:
 
 Bad:
@@ -1331,7 +1331,7 @@ if failed:
 
 Categories: `pathlib`
 
-Use the `mkdir` function from the pathlib library instead of using the
+Use the `mkdir` method from the pathlib library instead of using the
 `mkdir` and `makedirs` functions from the `os` library: the pathlib library
 is more modern and provides better flexibility over the construction and
 manipulation of file paths.
@@ -1561,7 +1561,7 @@ In some situations the `.lstrip()`, `.rstrip()` and `.strip()` string
 methods can be written more succinctly: `strip()` is the same thing as
 calling both `lstrip()` and `rstrip()` together, and all the strip
 functions take an iterable argument of the characters to strip, meaning
-you don't need to call a strip function multiple times with different
+you don't need to call strip methods multiple times with different
 arguments, you can just concatenate them and call it once.
 
 Bad:
@@ -1873,7 +1873,7 @@ if name == "bob":
 
 Categories: `pathlib`
 
-When checking the file extension for a pathlib object don't call
+When checking the file extension for a Path object don't call
 `endswith()` on the `name` field, directly check against `suffix` instead.
 
 Bad:
@@ -1928,7 +1928,7 @@ def add_defaults(settings: dict[str, str]) -> dict[str, str]:
 
 Categories: `readability` `secrets`
 
-Depending on how you are using the `secrets` module there might be a more
+Depending on how you are using the `secrets` module, there might be more
 expressive ways of writing what it is you're trying to write.
 
 Bad: