pathlint 0.3.0__tar.gz → 0.3.1__tar.gz

pathlint-0.3.1/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: pathlint
+Version: 0.3.1
+Summary: Fast linter to detect os.path usage and encourage pathlib adoption
+Project-URL: Repository, https://github.com/pszemraj/pathlint
+Project-URL: Issues, https://github.com/pszemraj/pathlint/issues
+Project-URL: Changelog, https://github.com/pszemraj/pathlint/releases
+Project-URL: Documentation, https://github.com/pszemraj/pathlint#readme
+Author-email: Peter Szemraj <peterszemraj+dev@gmail.com>
+License: MIT
+License-File: LICENSE.txt
+Keywords: code-quality,linter,os.path,pathlib,pre-commit,python-linter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pathlint
+
+Find `os.path` usage in Python code and migrate supported calls to `pathlib`.
+
+## Example
+
+```python
+# Before
+import os
+
+filename = os.path.join("src", "file.py")
+
+# With pathlib (keeping a string result)
+from pathlib import Path
+
+filename = str(Path("src") / "file.py")
+```
+
+Find places to migrate, then preview the changes pathlint can make:
+
+```bash
+pathlint check .
+pathlint fix . --dry-run
+```
+
+## Installation
+
+Requires **Python 3.9+**. No runtime dependencies.
+
+```bash
+pip install pathlint
+pathlint --version
+```
+
+## Quick start
+
+Check a project, a directory, or individual files:
+
+```bash
+pathlint check .
+pathlint check src/ tests/
+pathlint check myfile.py
+```
+
+Diagnostics point to the source line so you can review each use:
+
+```text
+src/utils.py:12: PL001 os.path usage: os.path.exists(value)
+Found 1 violation in 1 of 42 files checked.
+```
+
+Preview experimental fixes without changing files:
+
+```bash
+pathlint fix . --dry-run
+```
+
+For a file containing `import os` and the join call, the preview shows:
+
+```diff
+--- example.py
++++ example.py (fixed)
+@@ -1,2 +1,3 @@
+ import os
+-filename = os.path.join("src", "file.py")
++from pathlib import Path as _Path
++filename = str(_Path("src", "file.py"))
+```
+
+**Review the diff before applying it, then run your tests:**
+
+```bash
+pathlint fix .
+```
+
+After applying fixes, rerun `pathlint check .` to see which uses need
+manual migration.
+
+List the Python files that any of these commands would select:
+
+```bash
+pathlint files .
+```
+
+Use this listing to confirm your exclusions before applying fixes; it selects
+files without reading their Python source.
+
+Paths default to the current directory. Use `pathlint --help` or
+`pathlint check --help` to explore the CLI; `python -m pathlint check .` also
+works when you prefer module invocation.
+
+## What it detects
+
+```python
+import os
+import os.path as osp
+from os.path import exists as present
+
+os.path.exists("file")
+osp.join("directory", "file")
+present("file")
+callback = os.path.join
+```
+
+Pathlint resolves imports, aliases, and local shadowing, including usage in
+annotations. Valid `os.PathLike` annotations are not flagged. Detection is
+static: dynamic rebinding and wildcard imports may leave uses undetected.
+See [detection details](docs/detection.md) for advanced cases.
+
+## Auto-fix
+
+**Fixing is experimental. Review every diff and run your tests.**
+
+Only these five calls support automatic fixes, with string-literal arguments:
+
+| Usage | Pathlib replacement |
+| --- | --- |
+| `join` | `str(Path(...))` |
+| `basename` | `Path(...).name` |
+| `dirname` | `str(Path(...).parent)` |
+| `isabs` | `Path(...).is_absolute()` |
+| `expanduser` (without `~`) | `str(Path(...).expanduser())` |
+| `exists`, `isfile`, `isdir` | Manual migration |
+| `abspath`, `splitext`, `sep`, `pathsep` | Manual migration |
+
+Fixes preserve surrounding comments and strings. Annotation usages are detected
+but never rewritten.
+
+The fixer is conservative: it rewrites calls only when its static checks allow
+them and leaves uncertain cases unchanged. It does not fix every violation.
+See [fixer limitations](docs/fixer.md) for skipped calls and path forms.
+
+## Common options
+
+Exclude directories or generated files; repeat `--exclude` / `-e` as needed:
+
+```bash
+pathlint check . --exclude vendor -e "*.generated.py"
+```
+
+Directory scans respect Git ignore rules when Git is available and skip common
+generated directories by default. Preview selection with `pathlint files .`;
+see [file-selection rules](docs/file-selection.md) for exact matching behavior.
+
+```bash
+# Findings only, without a summary
+pathlint check . --quiet
+
+# Five files with the most violations
+pathlint check . --stats
+
+# Machine-readable report
+pathlint check . --output-format json
+
+# Fix preview without a summary or terminal colors
+pathlint fix . --dry-run --quiet --no-color
+```
+
+For scripting, `check` exits `0` when clean and `1` when it finds violations;
+`fix --dry-run` exits `1` when it proposes edits. Errors exit `2`.
+See the [CLI reference](docs/cli.md) for output formats, exit codes, and
+migration from older commands.
+
+## Pre-commit
+
+Add to `.pre-commit-config.yaml`, pinning the release you want to use:
+
+```yaml
+repos:
+  - repo: https://github.com/pszemraj/pathlint
+    rev: v0.3.0
+    hooks:
+      - id: pathlint
+        args: [--exclude, vendor, --exclude, backups]
+```
+
+Install and run the hook:
+
+```bash
+pre-commit install
+pre-commit run pathlint --all-files
+```
+
+The `pathlint` hook runs `pathlint check`. Use `pathlint-fix` instead to apply
+experimental fixes, and review its changes before committing.
+
+## Development
+
+Install the development dependencies, run the tests, and check style:
+
+```bash
+pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+```
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt).

pathlint-0.3.1/README.md

@@ -0,0 +1,200 @@
+# pathlint
+
+Find `os.path` usage in Python code and migrate supported calls to `pathlib`.
+
+## Example
+
+```python
+# Before
+import os
+
+filename = os.path.join("src", "file.py")
+
+# With pathlib (keeping a string result)
+from pathlib import Path
+
+filename = str(Path("src") / "file.py")
+```
+
+Find places to migrate, then preview the changes pathlint can make:
+
+```bash
+pathlint check .
+pathlint fix . --dry-run
+```
+
+## Installation
+
+Requires **Python 3.9+**. No runtime dependencies.
+
+```bash
+pip install pathlint
+pathlint --version
+```
+
+## Quick start
+
+Check a project, a directory, or individual files:
+
+```bash
+pathlint check .
+pathlint check src/ tests/
+pathlint check myfile.py
+```
+
+Diagnostics point to the source line so you can review each use:
+
+```text
+src/utils.py:12: PL001 os.path usage: os.path.exists(value)
+Found 1 violation in 1 of 42 files checked.
+```
+
+Preview experimental fixes without changing files:
+
+```bash
+pathlint fix . --dry-run
+```
+
+For a file containing `import os` and the join call, the preview shows:
+
+```diff
+--- example.py
++++ example.py (fixed)
+@@ -1,2 +1,3 @@
+ import os
+-filename = os.path.join("src", "file.py")
++from pathlib import Path as _Path
++filename = str(_Path("src", "file.py"))
+```
+
+**Review the diff before applying it, then run your tests:**
+
+```bash
+pathlint fix .
+```
+
+After applying fixes, rerun `pathlint check .` to see which uses need
+manual migration.
+
+List the Python files that any of these commands would select:
+
+```bash
+pathlint files .
+```
+
+Use this listing to confirm your exclusions before applying fixes; it selects
+files without reading their Python source.
+
+Paths default to the current directory. Use `pathlint --help` or
+`pathlint check --help` to explore the CLI; `python -m pathlint check .` also
+works when you prefer module invocation.
+
+## What it detects
+
+```python
+import os
+import os.path as osp
+from os.path import exists as present
+
+os.path.exists("file")
+osp.join("directory", "file")
+present("file")
+callback = os.path.join
+```
+
+Pathlint resolves imports, aliases, and local shadowing, including usage in
+annotations. Valid `os.PathLike` annotations are not flagged. Detection is
+static: dynamic rebinding and wildcard imports may leave uses undetected.
+See [detection details](docs/detection.md) for advanced cases.
+
+## Auto-fix
+
+**Fixing is experimental. Review every diff and run your tests.**
+
+Only these five calls support automatic fixes, with string-literal arguments:
+
+| Usage | Pathlib replacement |
+| --- | --- |
+| `join` | `str(Path(...))` |
+| `basename` | `Path(...).name` |
+| `dirname` | `str(Path(...).parent)` |
+| `isabs` | `Path(...).is_absolute()` |
+| `expanduser` (without `~`) | `str(Path(...).expanduser())` |
+| `exists`, `isfile`, `isdir` | Manual migration |
+| `abspath`, `splitext`, `sep`, `pathsep` | Manual migration |
+
+Fixes preserve surrounding comments and strings. Annotation usages are detected
+but never rewritten.
+
+The fixer is conservative: it rewrites calls only when its static checks allow
+them and leaves uncertain cases unchanged. It does not fix every violation.
+See [fixer limitations](docs/fixer.md) for skipped calls and path forms.
+
+## Common options
+
+Exclude directories or generated files; repeat `--exclude` / `-e` as needed:
+
+```bash
+pathlint check . --exclude vendor -e "*.generated.py"
+```
+
+Directory scans respect Git ignore rules when Git is available and skip common
+generated directories by default. Preview selection with `pathlint files .`;
+see [file-selection rules](docs/file-selection.md) for exact matching behavior.
+
+```bash
+# Findings only, without a summary
+pathlint check . --quiet
+
+# Five files with the most violations
+pathlint check . --stats
+
+# Machine-readable report
+pathlint check . --output-format json
+
+# Fix preview without a summary or terminal colors
+pathlint fix . --dry-run --quiet --no-color
+```
+
+For scripting, `check` exits `0` when clean and `1` when it finds violations;
+`fix --dry-run` exits `1` when it proposes edits. Errors exit `2`.
+See the [CLI reference](docs/cli.md) for output formats, exit codes, and
+migration from older commands.
+
+## Pre-commit
+
+Add to `.pre-commit-config.yaml`, pinning the release you want to use:
+
+```yaml
+repos:
+  - repo: https://github.com/pszemraj/pathlint
+    rev: v0.3.0
+    hooks:
+      - id: pathlint
+        args: [--exclude, vendor, --exclude, backups]
+```
+
+Install and run the hook:
+
+```bash
+pre-commit install
+pre-commit run pathlint --all-files
+```
+
+The `pathlint` hook runs `pathlint check`. Use `pathlint-fix` instead to apply
+experimental fixes, and review its changes before committing.
+
+## Development
+
+Install the development dependencies, run the tests, and check style:
+
+```bash
+pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+```
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt).

pathlint-0.3.1/docs/cli.md

@@ -0,0 +1,149 @@
+# CLI reference
+
+Use `pathlint check` to detect usage, `pathlint fix` to apply experimental
+migrations, and `pathlint files` to list selected files. Each command accepts
+files or directories and defaults to the current directory. A subcommand is
+required: bare `pathlint` prints usage and exits with status `2`.
+
+```bash
+pathlint --help
+pathlint check --help
+pathlint fix --help
+pathlint files --help
+python -m pathlint check .
+```
+
+See [file selection](file-selection.md) for exclusions and Git rules, and
+[fixer limitations](fixer.md) before applying changes.
+
+## Text output
+
+```text
+src/utils.py:12: PL001 os.path usage: os.path.exists(value)
+Found 1 violation in 1 of 42 files checked.
+The experimental fixer supports some calls; other usages need manual migration.
+```
+
+Paths are relative to the working directory when possible, and absolute for
+external files. Text output retains the stream's encoding and escapes characters
+it cannot represent, including when redirected through legacy Windows encodings.
+Each offending source line is reported once, even if it contains several usages.
+`PL001` means "Use pathlib instead of os.path."
+
+```bash
+# Findings only; no summary
+pathlint check . --quiet
+
+# Show the five files with the most violations
+pathlint check . --stats
+
+# Optional aggressive message
+pathlint check . --aggressive
+```
+
+`check --aggressive` adds `WARNING: ARE YOU KIDDING ME? USE PATHLIB!` after the
+summary when violations are found. It changes only the message, not detection
+or the exit code. `--quiet` suppresses the message.
+
+Text-mode errors go to stderr.
+
+## JSON output
+
+```bash
+pathlint check . --output-format json
+pathlint check . --output-format json --stats
+```
+
+For `example.py` containing:
+
+```python
+import os
+
+filename = os.path.join("src", "file.py")
+```
+
+`pathlint check example.py --output-format json` produces:
+
+```json
+{
+  "diagnostics": [
+    {
+      "path": "example.py",
+      "line": 3,
+      "code": "PL001",
+      "message": "Use pathlib instead of os.path",
+      "source": "filename = os.path.join(\"src\", \"file.py\")"
+    }
+  ],
+  "errors": [],
+  "summary": {
+    "files_checked": 1,
+    "files_with_issues": 1,
+    "violations": 1,
+    "errors": 0
+  }
+}
+```
+
+JSON reports contain `diagnostics`, `errors`, and `summary`. Each diagnostic has
+`path`, `line`, `code`, `message`, and `source`. Summary fields are
+`files_checked`, `files_with_issues`, `violations`, and `errors`; files that fail
+reading or parsing are not counted as checked. `--stats` adds a `statistics`
+list containing up to five `{path, violations}` entries.
+
+JSON is available only for `check` and cannot be combined with `--quiet` or
+`--aggressive`. Runtime errors are included in the JSON report without mixing
+text into stdout.
+
+## Fix output
+
+```bash
+# Review a unified diff without changing files
+pathlint fix src/ --dry-run
+
+# Apply supported migrations
+pathlint fix src/
+
+# Print only the diff
+pathlint fix src/ --dry-run --quiet
+
+# Disable terminal diff colors
+pathlint fix src/ --dry-run --no-color
+```
+
+Diff colors are enabled only on interactive terminals.
+
+The summary reminds you to run `pathlint check` for remaining usages that may
+need manual migration. Replacement totals include import edits; they are not a
+count of resolved `PL001` lines. `--quiet` suppresses these summaries.
+
+## Exit codes
+
+| Command | `0` | `1` | `2` |
+| --- | --- | --- | --- |
+| `check` | Clean or no files selected | Violations found | Input, discovery, read, or parse error |
+| `fix` | Completed | - | Input, discovery, read, parse, or write error |
+| `fix --dry-run` | No edits proposed | Edits proposed | Error |
+| `files` | Listing completed, including empty selection | - | Input or discovery error |
+
+Errors take precedence over violations or proposed edits. Other valid files
+are still processed. Ctrl-C exits with status `130`.
+
+## Migrating legacy invocations
+
+Use explicit subcommands instead of the removed bare-path and fix-flag forms:
+
+| Removed invocation | Replacement |
+| --- | --- |
+| `pathlint` | `pathlint check` |
+| `pathlint .` | `pathlint check .` |
+| `pathlint --fix src/` | `pathlint fix src/` |
+| `pathlint --dry-run src/` | `pathlint fix src/ --dry-run` |
+| `python -m pathlint.linter src/` | `python -m pathlint check src/` |
+| `python -m pathlint.autofix src/` | `python -m pathlint fix src/` |
+
+`--stats` and `--aggressive` are check options; they are rejected by `fix`.
+Options may appear between paths. Use `--` before filenames beginning with `-`.
+Empty selections succeed; dry runs return `1` when they propose edits.
+
+Return to the [README](../README.md).

pathlint-0.3.1/docs/detection.md

@@ -0,0 +1,48 @@
+# Detection details
+
+Pathlint detects `os.path` imports, aliases, function references, calls, and
+usage in annotations:
+
+```python
+import os
+import os as system
+import os.path as osp
+from os import path as paths
+from os.path import exists as present
+
+os.path.exists("file")
+system.path.join("directory", "file")
+osp.isdir("directory")
+paths.dirname(__file__)
+present("file")
+callback = os.path.join
+```
+
+## Binding resolution
+
+Pathlint resolves imported names in function, class, and comprehension scopes
+so ordinary local shadowing is not mistaken for `os.path`. Private aliases in
+class scopes are left unresolved because Python mangles their names. Deleted
+class locals and cleared exception aliases fall back to module globals.
+
+Function and generator bodies use the enclosing scope's final bindings for
+detection; a generator's first iterable is inspected immediately. Dynamic
+rebinding can prevent resolution. Wildcard imports invalidate tracked bindings;
+later explicit imports can restore them.
+
+Detection inspects `if` branches independently and uses literal conditions
+when merging bindings in the current scope. Loop bindings are merged
+conservatively across iterations and `else` suites. This is a static check,
+not full Python execution analysis.
+
+## Annotations
+
+Expressions in annotations are checked too. Valid `os.PathLike` annotations
+are not `os.path` usage and are not flagged. The fixer leaves annotation
+expressions unchanged: postponed annotations and Python 3.14's lazy annotations
+can resolve names after their bindings change.
+
+Detection does not imply that a use can be fixed. See the
+[fixer limitations](fixer.md) for the stricter migration rules.
+
+Return to the [README](../README.md).

pathlint-0.3.1/docs/file-selection.md

@@ -0,0 +1,68 @@
+# File selection
+
+`check`, `fix`, and `files` share the same selection rules. Use `files` to
+inspect the selected Python files without parsing or modifying them:
+
+```bash
+pathlint files .
+pathlint check . --exclude vendor --exclude 'training/wandb/*' --exclude backups
+pathlint files . -e '*.generated.py' -e 'src/legacy/'
+pathlint fix . --exclude vendor --dry-run
+```
+
+## Selection precedence
+
+1. Explicit `--exclude` patterns apply to every input, including named files
+   and filenames supplied by pre-commit.
+2. Explicitly named Python files bypass Git and built-in exclusions.
+3. Directory scans apply built-in exclusions and, when Git is available and
+   enabled, select tracked files and untracked files that Git does not ignore.
+
+File symlinks select their resolved Python targets once; exclusions match both
+the link and target paths.
+
+## Exclusion patterns
+
+Each `-e` / `--exclude` accepts one pattern; repeat the argument for multiple
+patterns. Explicit exclusions add to the built-in exclusions.
+
+- Names without `/`, such as `backups` or `test_*.py`, match at any depth.
+- Patterns containing `/` match paths relative to the working directory.
+  `./vendor` matches the top-level `vendor`, while `vendor` matches that name
+  anywhere. Absolute patterns can exclude paths outside the working directory.
+- Directory matches exclude their descendants. A trailing `/` restricts a
+  pattern to directories.
+- Patterns use case-sensitive `fnmatch` syntax: `*`, `?`, and bracket expressions.
+  `*` can span `/`; `**` has no additional meaning. Quote wildcards to prevent
+  shell expansion. These patterns do not support Git-style `!` negation.
+
+Built-in directory exclusions are `__pycache__`, `.venv`, `venv`, `.git`,
+`node_modules`, `.tox`, `build`, `dist`, `.mypy_cache`, `.pytest_cache`,
+`.ruff_cache`, `.nox`, `.eggs`, `*.egg-info`, `site-packages`, `.idea`, and
+`.vscode`. The `*.egg-info` pattern matches directory names such as
+`pathlint.egg-info`; explicitly named Python files still bypass these defaults.
+
+Disable Git ignores or built-in exclusions independently:
+
+```bash
+pathlint check . --no-gitignore
+pathlint check . --no-default-excludes
+```
+
+## Git rules
+
+In Git worktrees, directory scans include tracked files and untracked files
+that Git does not ignore. Git handles nested `.gitignore` rules, negation,
+repository-local excludes, and global ignores. Tracked files remain eligible
+even when they match an ignore rule. Nonexcluded nested repositories use their
+own Git rules.
+
+Unreadable selected directories or Git ignore metadata produce discovery errors.
+Warnings confined to excluded directories are suppressed. An unreadable global
+ignore file remains an error even when stored in an excluded directory, because
+it can affect the selected files elsewhere.
+
+Git is optional. Without Git, directory scans use built-in and explicit
+exclusions; `.gitignore` rules are not interpreted.
+
+Return to the [README](../README.md).