pathlib rule docs

crates/ruff/src/rules/flake8_use_pathlib/violations.rs

@@ -101,6 +101,30 @@ impl Violation for OsUnlink {
 }
 
 // PTH109
+
+/// ## What is does
+/// Detects the use of `os.getcwd` and `os.getcwdb`.
+///
+/// ## Why is this bad?
+/// `pathlib` offers high-level path manipulations of paths, `os.path` offers low-level manipulation of paths.
+/// Where possible, using `Path` object methods such as `Path.cwd()` improve readability over `os.getcwd()`.
+/// (Exceptions might be in loops where the `Path` object overhead is high.)
+///
+/// ## Examples
+/// ```python
+/// cwd = os.getcwd()
+/// ```
+///
+/// Use instead:
+/// ```python
+/// cwd = Path.cwd()
+/// ```
+///
+/// ## References
+/// * [PEP 428](https://peps.python.org/pep-0428/)
+/// * [Correspondence between `os` and `pathlib`](https://docs.python.org/3/library/pathlib.html#correspondence-to-tools-in-the-os-module)
+/// * [Why you should be using pathlib](https://treyhunner.com/2018/12/why-you-should-be-using-pathlib/)
+/// * [No really, pathlib is great](https://treyhunner.com/2019/01/no-really-pathlib-is-great/)
 #[violation]
 pub struct OsGetcwd;
 
@@ -167,6 +191,30 @@ impl Violation for OsPathIslink {
 }
 
 // PTH115
+
+/// ## What is does
+/// Detects the use of `os.readlink`.
+///
+/// ## Why is this bad?
+/// `pathlib` offers high-level path manipulations of paths, `os.path` offers low-level manipulation of paths.
+/// Where possible, using `Path` object methods such as `Path(x).readlink()` improve readability over `os.readlink(x)`.
+/// (Exceptions might be in loops where the `Path` object overhead is high.)
+///
+/// ## Examples
+/// ```python
+/// link = os.readlink(x)
+/// ```
+///
+/// Use instead:
+/// ```python
+/// link = Path(x).readlink()
+/// ```
+///
+/// ## References
+/// * [PEP 428](https://peps.python.org/pep-0428/)
+/// * [Correspondence between `os` and `pathlib`](https://docs.python.org/3/library/pathlib.html#correspondence-to-tools-in-the-os-module)
+/// * [Why you should be using pathlib](https://treyhunner.com/2018/12/why-you-should-be-using-pathlib/)
+/// * [No really, pathlib is great](https://treyhunner.com/2019/01/no-really-pathlib-is-great/)
 #[violation]
 pub struct OsReadlink;