pyupcheck 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AgbaDev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,116 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyupcheck
3
+ Version: 0.1.0
4
+ Summary: Check if upgrading a Python dependency will break your code
5
+ Author: AgbaDev
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/AgbaDev/pyupcheck
8
+ Project-URL: Issues, https://github.com/AgbaDev/pyupcheck/issues
9
+ Keywords: cli,dependency,upgrade,migration,breaking-changes
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development :: Quality Assurance
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: httpx>=0.24.0
19
+ Requires-Dist: rich>=13.0.0
20
+ Requires-Dist: click>=8.0.0
21
+ Dynamic: license-file
22
+
23
+ # pyupcheck
24
+
25
+ Check if upgrading a Python dependency will break your code.
26
+
27
+ ```
28
+ $ pyupcheck check requests 3.0.0
29
+
30
+ pyupcheck 2.31.0 -> 3.0.0
31
+
32
+ Found 14 usages across 5 files.
33
+ Found 3 potentially breaking/deprecated changes.
34
+
35
+ BREAKING (1):
36
+
37
+ x src/api.py:23 resp = requests.get(url, verify=False)
38
+ Removed: `verify` parameter no longer accepted
39
+
40
+ DEPRECATED (1):
41
+
42
+ ! src/utils.py:8 from requests.packages import urllib3
43
+ Deprecated: use `urllib3` directly instead
44
+
45
+ 12 other usages are safe.
46
+
47
+ ╭─ pyupcheck report ──────────────────────────────────╮
48
+ │ Upgrade risky. 1 breaking change(s) affect your │
49
+ │ code. │
50
+ ╰────────────────────────────────────────────────────╯
51
+ ```
52
+
53
+ ## Install
54
+
55
+ ```bash
56
+ pip install pyupcheck
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ ### Check an upgrade
62
+
63
+ ```bash
64
+ # check against a specific version
65
+ pyupcheck check flask 3.0.0
66
+
67
+ # check against the latest version
68
+ pyupcheck check flask
69
+
70
+ # scan a specific directory
71
+ pyupcheck check requests 3.0.0 --dir ./src
72
+
73
+ # json output for CI
74
+ pyupcheck check requests 3.0.0 --json-output
75
+ ```
76
+
77
+ Exit code is 1 if breaking changes are found, 0 otherwise. Use this in CI to gate upgrades.
78
+
79
+ ### Scan your code
80
+
81
+ ```bash
82
+ # just see what APIs you use from a package
83
+ pyupcheck scan requests
84
+ ```
85
+
86
+ ### List versions
87
+
88
+ ```bash
89
+ pyupcheck versions flask
90
+ ```
91
+
92
+ ## How it works
93
+
94
+ 1. Scans your `.py` files with AST parsing to find every import and usage of the target package
95
+ 2. Fetches the changelog from GitHub releases and PyPI metadata
96
+ 3. Parses the changelog for breaking changes, deprecations, and renames
97
+ 4. Cross-references your usage against the changes
98
+ 5. Reports which of your usages are at risk
99
+
100
+ ## Limitations
101
+
102
+ - Changelog parsing relies on maintainers writing structured changelogs. If a project has unstructured notes, pyupcheck may miss changes.
103
+ - Dynamic attribute access (`getattr(requests, method_name)`) is not detected.
104
+ - Only scans `.py` files (not Jupyter notebooks, config files, etc.)
105
+
106
+ ## Options
107
+
108
+ | Flag | Description |
109
+ |------|-------------|
110
+ | `--dir`, `-d` | Directory to scan (default: `.`) |
111
+ | `--github-token` | GitHub token for higher API rate limits (or set `GITHUB_TOKEN` env var) |
112
+ | `--json-output`, `-j` | Output as JSON |
113
+
114
+ ## License
115
+
116
+ MIT
@@ -0,0 +1,94 @@
1
+ # pyupcheck
2
+
3
+ Check if upgrading a Python dependency will break your code.
4
+
5
+ ```
6
+ $ pyupcheck check requests 3.0.0
7
+
8
+ pyupcheck 2.31.0 -> 3.0.0
9
+
10
+ Found 14 usages across 5 files.
11
+ Found 3 potentially breaking/deprecated changes.
12
+
13
+ BREAKING (1):
14
+
15
+ x src/api.py:23 resp = requests.get(url, verify=False)
16
+ Removed: `verify` parameter no longer accepted
17
+
18
+ DEPRECATED (1):
19
+
20
+ ! src/utils.py:8 from requests.packages import urllib3
21
+ Deprecated: use `urllib3` directly instead
22
+
23
+ 12 other usages are safe.
24
+
25
+ ╭─ pyupcheck report ──────────────────────────────────╮
26
+ │ Upgrade risky. 1 breaking change(s) affect your │
27
+ │ code. │
28
+ ╰────────────────────────────────────────────────────╯
29
+ ```
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ pip install pyupcheck
35
+ ```
36
+
37
+ ## Usage
38
+
39
+ ### Check an upgrade
40
+
41
+ ```bash
42
+ # check against a specific version
43
+ pyupcheck check flask 3.0.0
44
+
45
+ # check against the latest version
46
+ pyupcheck check flask
47
+
48
+ # scan a specific directory
49
+ pyupcheck check requests 3.0.0 --dir ./src
50
+
51
+ # json output for CI
52
+ pyupcheck check requests 3.0.0 --json-output
53
+ ```
54
+
55
+ Exit code is 1 if breaking changes are found, 0 otherwise. Use this in CI to gate upgrades.
56
+
57
+ ### Scan your code
58
+
59
+ ```bash
60
+ # just see what APIs you use from a package
61
+ pyupcheck scan requests
62
+ ```
63
+
64
+ ### List versions
65
+
66
+ ```bash
67
+ pyupcheck versions flask
68
+ ```
69
+
70
+ ## How it works
71
+
72
+ 1. Scans your `.py` files with AST parsing to find every import and usage of the target package
73
+ 2. Fetches the changelog from GitHub releases and PyPI metadata
74
+ 3. Parses the changelog for breaking changes, deprecations, and renames
75
+ 4. Cross-references your usage against the changes
76
+ 5. Reports which of your usages are at risk
77
+
78
+ ## Limitations
79
+
80
+ - Changelog parsing relies on maintainers writing structured changelogs. If a project has unstructured notes, pyupcheck may miss changes.
81
+ - Dynamic attribute access (`getattr(requests, method_name)`) is not detected.
82
+ - Only scans `.py` files (not Jupyter notebooks, config files, etc.)
83
+
84
+ ## Options
85
+
86
+ | Flag | Description |
87
+ |------|-------------|
88
+ | `--dir`, `-d` | Directory to scan (default: `.`) |
89
+ | `--github-token` | GitHub token for higher API rate limits (or set `GITHUB_TOKEN` env var) |
90
+ | `--json-output`, `-j` | Output as JSON |
91
+
92
+ ## License
93
+
94
+ MIT
@@ -0,0 +1,3 @@
1
+ """depshift - Check if upgrading a Python dependency will break your code."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,75 @@
1
+ """Cross-reference code usages against changelog changes."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import List, Optional
5
+
6
+ from depshift.scanner import Usage
7
+ from depshift.changelog import ChangeEntry
8
+
9
+
10
+ @dataclass
11
+ class Risk:
12
+ """A usage that may be affected by a change."""
13
+ usage: Usage
14
+ change: ChangeEntry
15
+ severity: str # "breaking", "deprecated", "warning"
16
+
17
+
18
+ def normalize_api(api: str, package: str) -> str:
19
+ """Normalize an API string for comparison."""
20
+ api = api.strip().rstrip("()")
21
+ # ensure it starts with package name
22
+ if not api.startswith(f"{package}.") and api != package:
23
+ api = f"{package}.{api}"
24
+ return api.lower()
25
+
26
+
27
+ def match_usage_to_change(usage: Usage, change: ChangeEntry, package: str) -> Optional[Risk]:
28
+ """Check if a usage is affected by a change."""
29
+ usage_api = normalize_api(usage.attr_chain, package)
30
+ change_api = normalize_api(change.api, package)
31
+
32
+ # direct match
33
+ if usage_api == change_api:
34
+ severity = "breaking" if change.kind in ("removed", "changed") else "deprecated"
35
+ return Risk(usage=usage, change=change, severity=severity)
36
+
37
+ # usage is a child of the changed API (e.g. change affects requests.Session,
38
+ # usage is requests.Session.get)
39
+ if usage_api.startswith(f"{change_api}."):
40
+ severity = "breaking" if change.kind in ("removed", "changed") else "deprecated"
41
+ return Risk(usage=usage, change=change, severity=severity)
42
+
43
+ # change is a child of something the usage touches
44
+ if change_api.startswith(f"{usage_api}."):
45
+ severity = "warning"
46
+ return Risk(usage=usage, change=change, severity=severity)
47
+
48
+ return None
49
+
50
+
51
+ def analyze(usages: List[Usage], changes: List[ChangeEntry], package: str) -> tuple:
52
+ """
53
+ Cross-reference usages against changes.
54
+ Returns (risks, safe_usages).
55
+ """
56
+ risks: List[Risk] = []
57
+ matched_usage_keys = set()
58
+
59
+ for usage in usages:
60
+ for change in changes:
61
+ risk = match_usage_to_change(usage, change, package)
62
+ if risk:
63
+ risks.append(risk)
64
+ matched_usage_keys.add((usage.file, usage.line, usage.attr_chain))
65
+
66
+ safe_usages = [
67
+ u for u in usages
68
+ if (u.file, u.line, u.attr_chain) not in matched_usage_keys
69
+ ]
70
+
71
+ # sort risks: breaking first, then deprecated, then warning
72
+ severity_order = {"breaking": 0, "deprecated": 1, "warning": 2}
73
+ risks.sort(key=lambda r: severity_order.get(r.severity, 99))
74
+
75
+ return risks, safe_usages
@@ -0,0 +1,288 @@
1
+ """Fetch changelog and deprecation data for a package version."""
2
+
3
+ import re
4
+ from dataclasses import dataclass
5
+ from typing import List, Optional, Tuple
6
+
7
+ import httpx
8
+
9
+
10
+ @dataclass
11
+ class ChangeEntry:
12
+ """A single breaking or deprecated API change."""
13
+ kind: str # "removed", "deprecated", "changed", "renamed"
14
+ api: str # the affected API path, e.g. "requests.get.verify"
15
+ description: str
16
+ version: str # version where this change happened
17
+
18
+
19
+ PYPI_API = "https://pypi.org/pypi/{package}/json"
20
+ PYPI_VERSION_API = "https://pypi.org/pypi/{package}/{version}/json"
21
+ GITHUB_RELEASES_API = "https://api.github.com/repos/{owner}/{repo}/releases"
22
+ GITHUB_TAGS_API = "https://api.github.com/repos/{owner}/{repo}/tags"
23
+
24
+
25
+ def get_pypi_info(package: str) -> dict:
26
+ """Fetch full package info from PyPI."""
27
+ url = PYPI_API.format(package=package)
28
+ resp = httpx.get(url, timeout=15, follow_redirects=True)
29
+ resp.raise_for_status()
30
+ return resp.json()
31
+
32
+
33
+ def get_pypi_version_info(package: str, version: str) -> dict:
34
+ """Fetch info for a specific version."""
35
+ url = PYPI_VERSION_API.format(package=package, version=version)
36
+ resp = httpx.get(url, timeout=15, follow_redirects=True)
37
+ resp.raise_for_status()
38
+ return resp.json()
39
+
40
+
41
+ def get_available_versions(package: str) -> List[str]:
42
+ """Get all available versions for a package."""
43
+ info = get_pypi_info(package)
44
+ return list(info.get("releases", {}).keys())
45
+
46
+
47
+ def get_current_version(package: str) -> str:
48
+ """Get the latest version of a package on PyPI."""
49
+ info = get_pypi_info(package)
50
+ return info["info"]["version"]
51
+
52
+
53
+ def extract_github_repo(pypi_info: dict) -> Optional[Tuple[str, str]]:
54
+ """Try to find the GitHub owner/repo from PyPI metadata."""
55
+ info = pypi_info.get("info", {})
56
+ urls = []
57
+
58
+ project_urls = info.get("project_urls") or {}
59
+ for key, val in project_urls.items():
60
+ if val:
61
+ urls.append(val)
62
+
63
+ home = info.get("home_page")
64
+ if home:
65
+ urls.append(home)
66
+
67
+ pattern = re.compile(r"github\.com/([^/]+)/([^/\s#?]+)")
68
+ for url in urls:
69
+ m = pattern.search(url)
70
+ if m:
71
+ owner, repo = m.group(1), m.group(2)
72
+ repo = repo.rstrip(".git")
73
+ return owner, repo
74
+ return None
75
+
76
+
77
+ def fetch_github_releases(owner: str, repo: str, token: Optional[str] = None) -> List[dict]:
78
+ """Fetch releases from GitHub."""
79
+ headers = {"Accept": "application/vnd.github+json"}
80
+ if token:
81
+ headers["Authorization"] = f"Bearer {token}"
82
+
83
+ releases = []
84
+ page = 1
85
+ while page <= 5: # cap at 5 pages
86
+ url = f"{GITHUB_RELEASES_API.format(owner=owner, repo=repo)}?per_page=50&page={page}"
87
+ resp = httpx.get(url, headers=headers, timeout=15, follow_redirects=True)
88
+ if resp.status_code != 200:
89
+ break
90
+ batch = resp.json()
91
+ if not batch:
92
+ break
93
+ releases.extend(batch)
94
+ page += 1
95
+ return releases
96
+
97
+
98
+ def parse_changelog_text(text: str, version: str) -> List[ChangeEntry]:
99
+ """Parse a changelog/release notes body for breaking/deprecated changes."""
100
+ entries: List[ChangeEntry] = []
101
+ if not text:
102
+ return entries
103
+
104
+ lines = text.splitlines()
105
+
106
+ # patterns that signal breaking/deprecation info
107
+ breaking_patterns = [
108
+ re.compile(r"remov(ed?|ing|al)\b", re.IGNORECASE),
109
+ re.compile(r"delet(ed?|ing)\b", re.IGNORECASE),
110
+ re.compile(r"drop(ped|ping)?\b", re.IGNORECASE),
111
+ re.compile(r"break(ing|s)?\b", re.IGNORECASE),
112
+ re.compile(r"backwards?\s*incompatible", re.IGNORECASE),
113
+ re.compile(r"no\s*longer\s*(support|available|accept)", re.IGNORECASE),
114
+ ]
115
+ deprecation_patterns = [
116
+ re.compile(r"deprecat(ed?|ing|ion)\b", re.IGNORECASE),
117
+ re.compile(r"will\s*be\s*removed", re.IGNORECASE),
118
+ re.compile(r"use\s+\S+\s+instead", re.IGNORECASE),
119
+ ]
120
+ rename_patterns = [
121
+ re.compile(r"renam(ed?|ing)\b", re.IGNORECASE),
122
+ re.compile(r"moved?\s*(to|from)\b", re.IGNORECASE),
123
+ ]
124
+
125
+ # try to extract python identifiers from a line
126
+ api_pattern = re.compile(r"`([a-zA-Z_][\w.]*(?:\(\))?)`")
127
+ fallback_api_pattern = re.compile(r"(?:^|\s)([a-zA-Z_][\w]*\.[a-zA-Z_][\w.]*(?:\(\))?)")
128
+
129
+ for line in lines:
130
+ line_stripped = line.strip().lstrip("-*• ")
131
+ if not line_stripped:
132
+ continue
133
+
134
+ kind = None
135
+ for p in breaking_patterns:
136
+ if p.search(line_stripped):
137
+ kind = "removed"
138
+ break
139
+ if not kind:
140
+ for p in deprecation_patterns:
141
+ if p.search(line_stripped):
142
+ kind = "deprecated"
143
+ break
144
+ if not kind:
145
+ for p in rename_patterns:
146
+ if p.search(line_stripped):
147
+ kind = "renamed"
148
+ break
149
+
150
+ if not kind:
151
+ continue
152
+
153
+ # extract API references
154
+ apis = api_pattern.findall(line_stripped)
155
+ if not apis:
156
+ apis = fallback_api_pattern.findall(line_stripped)
157
+
158
+ api_str = apis[0] if apis else "unknown"
159
+ api_str = api_str.rstrip("()")
160
+
161
+ entries.append(ChangeEntry(
162
+ kind=kind,
163
+ api=api_str,
164
+ description=line_stripped[:200],
165
+ version=version,
166
+ ))
167
+
168
+ return entries
169
+
170
+
171
+ CHANGELOG_FILENAMES = [
172
+ "CHANGES.rst", "CHANGELOG.rst", "CHANGELOG.md", "CHANGES.md",
173
+ "CHANGES", "CHANGELOG", "HISTORY.rst", "HISTORY.md",
174
+ "RELEASE_NOTES.md", "NEWS.rst", "NEWS.md",
175
+ ]
176
+
177
+
178
+ def fetch_raw_changelog(owner: str, repo: str, token: Optional[str] = None) -> Optional[str]:
179
+ """Try to fetch the raw changelog file from GitHub."""
180
+ headers = {}
181
+ if token:
182
+ headers["Authorization"] = f"Bearer {token}"
183
+
184
+ for branch in ["main", "master"]:
185
+ for fname in CHANGELOG_FILENAMES:
186
+ url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{fname}"
187
+ try:
188
+ resp = httpx.get(url, headers=headers, timeout=10, follow_redirects=True)
189
+ if resp.status_code == 200 and len(resp.text) > 50:
190
+ return resp.text
191
+ except Exception:
192
+ continue
193
+ return None
194
+
195
+
196
+ def parse_sectioned_changelog(text: str, package: str) -> List[ChangeEntry]:
197
+ """Parse a full changelog file that's divided by version headers."""
198
+ entries: List[ChangeEntry] = []
199
+
200
+ # match version headers like "Version 3.0.0", "## 3.0.0", "3.0.0 (2024-01-01)"
201
+ version_header = re.compile(
202
+ r"^(?:#{1,3}\s+)?(?:version\s+)?v?(\d+\.\d+(?:\.\d+)?(?:[a-z]\d*)?)\b",
203
+ re.IGNORECASE | re.MULTILINE,
204
+ )
205
+
206
+ splits = list(version_header.finditer(text))
207
+ if not splits:
208
+ return entries
209
+
210
+ for i, m in enumerate(splits):
211
+ ver = m.group(1)
212
+ start = m.end()
213
+ end = splits[i + 1].start() if i + 1 < len(splits) else len(text)
214
+ section = text[start:end]
215
+ section_entries = parse_changelog_text(section, ver)
216
+ entries.extend(section_entries)
217
+
218
+ return entries
219
+
220
+
221
+ def get_changes_between(package: str, current_version: str, target_version: str,
222
+ github_token: Optional[str] = None) -> List[ChangeEntry]:
223
+ """Get all breaking/deprecated changes between two versions."""
224
+ pypi_info = get_pypi_info(package)
225
+
226
+ repo_info = extract_github_repo(pypi_info)
227
+ all_entries: List[ChangeEntry] = []
228
+
229
+ if repo_info:
230
+ owner, repo = repo_info
231
+
232
+ # try github releases API first
233
+ try:
234
+ releases = fetch_github_releases(owner, repo, token=github_token)
235
+ for rel in releases:
236
+ tag = rel.get("tag_name", "")
237
+ body = rel.get("body", "") or ""
238
+ ver = tag.lstrip("vV")
239
+ entries = parse_changelog_text(body, ver)
240
+ all_entries.extend(entries)
241
+ except Exception:
242
+ pass
243
+
244
+ # if releases gave us nothing, try raw changelog file
245
+ if not all_entries:
246
+ try:
247
+ raw = fetch_raw_changelog(owner, repo, token=github_token)
248
+ if raw:
249
+ all_entries = parse_sectioned_changelog(raw, package)
250
+ except Exception:
251
+ pass
252
+
253
+ # also check the PyPI description for the target version
254
+ try:
255
+ ver_info = get_pypi_version_info(package, target_version)
256
+ desc = ver_info.get("info", {}).get("description", "")
257
+ if desc:
258
+ entries = parse_sectioned_changelog(desc, package)
259
+ all_entries.extend(entries)
260
+ except Exception:
261
+ pass
262
+
263
+ # filter to only changes relevant between current and target
264
+ from packaging.version import Version, InvalidVersion
265
+
266
+ try:
267
+ v_current = Version(current_version)
268
+ v_target = Version(target_version)
269
+ except InvalidVersion:
270
+ return all_entries
271
+
272
+ filtered = []
273
+ seen = set()
274
+ for entry in all_entries:
275
+ try:
276
+ v_entry = Version(entry.version)
277
+ if v_current < v_entry <= v_target:
278
+ key = (entry.kind, entry.api, entry.version)
279
+ if key not in seen:
280
+ seen.add(key)
281
+ filtered.append(entry)
282
+ except InvalidVersion:
283
+ key = (entry.kind, entry.api, entry.version)
284
+ if key not in seen:
285
+ seen.add(key)
286
+ filtered.append(entry)
287
+
288
+ return filtered
@@ -0,0 +1,269 @@
1
+ """CLI entry point for depshift."""
2
+
3
+ import os
4
+ import sys
5
+ from typing import Optional
6
+
7
+ import click
8
+ from rich.console import Console
9
+ from rich.table import Table
10
+ from rich.panel import Panel
11
+ from rich.text import Text
12
+
13
+ from depshift import __version__
14
+ from depshift.scanner import scan_directory
15
+ from depshift.changelog import (
16
+ get_changes_between,
17
+ get_current_version,
18
+ get_available_versions,
19
+ get_pypi_info,
20
+ )
21
+ from depshift.analyzer import analyze
22
+
23
+
24
+ console = Console()
25
+
26
+
27
+ def get_installed_version(package: str) -> Optional[str]:
28
+ """Try to get the locally installed version of a package."""
29
+ try:
30
+ from importlib.metadata import version
31
+ return version(package)
32
+ except Exception:
33
+ return None
34
+
35
+
36
+ @click.group()
37
+ @click.version_option(__version__, prog_name="pyupcheck")
38
+ def main():
39
+ """pyupcheck - Check if upgrading a Python dependency will break your code."""
40
+ pass
41
+
42
+
43
+ @main.command()
44
+ @click.argument("package")
45
+ @click.argument("target_version", required=False)
46
+ @click.option("--dir", "-d", "directory", default=".", help="Directory to scan (default: current dir)")
47
+ @click.option("--github-token", envvar="GITHUB_TOKEN", default=None, help="GitHub token for higher rate limits")
48
+ @click.option("--json-output", "-j", is_flag=True, help="Output as JSON")
49
+ def check(package: str, target_version: Optional[str], directory: str, github_token: Optional[str], json_output: bool):
50
+ """Check if upgrading PACKAGE to TARGET_VERSION will break your code.
51
+
52
+ If TARGET_VERSION is omitted, checks against the latest version on PyPI.
53
+ """
54
+ directory = os.path.abspath(directory)
55
+
56
+ # resolve current version
57
+ installed = get_installed_version(package)
58
+ if not installed:
59
+ console.print(f"[yellow]Warning:[/] {package} is not installed locally. "
60
+ "Cannot determine current version, will show all known changes.")
61
+
62
+ # resolve target version
63
+ if not target_version:
64
+ with console.status(f"Fetching latest version of [bold]{package}[/]..."):
65
+ try:
66
+ target_version = get_current_version(package)
67
+ except Exception as e:
68
+ console.print(f"[red]Error:[/] Could not find {package} on PyPI: {e}")
69
+ sys.exit(1)
70
+ console.print(f"Latest version: [bold]{target_version}[/]")
71
+
72
+ if installed and installed == target_version:
73
+ console.print(f"[green]You're already on {target_version}. Nothing to check.[/]")
74
+ sys.exit(0)
75
+
76
+ current = installed or "0.0.0"
77
+ console.print(f"\n[bold]depshift[/] {current} -> {target_version}\n")
78
+
79
+ # step 1: scan codebase
80
+ with console.status(f"Scanning [bold]{directory}[/] for usages of [bold]{package}[/]..."):
81
+ usages = scan_directory(directory, package)
82
+
83
+ if not usages:
84
+ console.print(f"[yellow]No usages of {package} found in {directory}[/]")
85
+ console.print("Nothing to check. You're safe to upgrade.")
86
+ sys.exit(0)
87
+
88
+ file_count = len(set(u.file for u in usages))
89
+ console.print(f"Found [bold]{len(usages)}[/] usages across [bold]{file_count}[/] files.\n")
90
+
91
+ # step 2: fetch changes
92
+ with console.status(f"Fetching changelog for [bold]{package}[/] {current} -> {target_version}..."):
93
+ try:
94
+ changes = get_changes_between(package, current, target_version, github_token=github_token)
95
+ except Exception as e:
96
+ console.print(f"[red]Error fetching changelog:[/] {e}")
97
+ changes = []
98
+
99
+ if not changes:
100
+ console.print("[yellow]No changelog data found.[/] Could not find breaking changes info.")
101
+ console.print("This could mean the upgrade is safe, or that the changelog isn't machine-readable.")
102
+ console.print(f"\nTip: check the changelog manually at the project's GitHub/docs.")
103
+ _print_usages_summary(usages, package)
104
+ sys.exit(0)
105
+
106
+ console.print(f"Found [bold]{len(changes)}[/] potentially breaking/deprecated changes.\n")
107
+
108
+ # step 3: cross-reference
109
+ risks, safe = analyze(usages, changes, package)
110
+
111
+ if json_output:
112
+ _print_json(risks, safe, package, current, target_version)
113
+ else:
114
+ _print_report(risks, safe, changes, package, current, target_version)
115
+
116
+ # exit code
117
+ breaking_count = sum(1 for r in risks if r.severity == "breaking")
118
+ sys.exit(1 if breaking_count > 0 else 0)
119
+
120
+
121
+ def _print_report(risks, safe, changes, package, current, target_version):
122
+ """Print a human-readable report."""
123
+ if not risks:
124
+ console.print(Panel(
125
+ f"[green bold]All clear![/]\n\n"
126
+ f"None of your {len(safe)} usages of {package} are affected by "
127
+ f"known changes in {target_version}.",
128
+ title="depshift report",
129
+ border_style="green",
130
+ ))
131
+ return
132
+
133
+ # breaking
134
+ breaking = [r for r in risks if r.severity == "breaking"]
135
+ deprecated = [r for r in risks if r.severity == "deprecated"]
136
+ warnings = [r for r in risks if r.severity == "warning"]
137
+
138
+ if breaking:
139
+ console.print(f"[red bold]BREAKING ({len(breaking)}):[/]\n")
140
+ for r in breaking:
141
+ rel_path = os.path.relpath(r.usage.file)
142
+ console.print(f" [red]x[/] [bold]{rel_path}:{r.usage.line}[/] {r.usage.code}")
143
+ console.print(f" [dim]{r.change.description}[/]\n")
144
+
145
+ if deprecated:
146
+ console.print(f"[yellow bold]DEPRECATED ({len(deprecated)}):[/]\n")
147
+ for r in deprecated:
148
+ rel_path = os.path.relpath(r.usage.file)
149
+ console.print(f" [yellow]![/] [bold]{rel_path}:{r.usage.line}[/] {r.usage.code}")
150
+ console.print(f" [dim]{r.change.description}[/]\n")
151
+
152
+ if warnings:
153
+ console.print(f"[blue bold]WARNINGS ({len(warnings)}):[/]\n")
154
+ for r in warnings:
155
+ rel_path = os.path.relpath(r.usage.file)
156
+ console.print(f" [blue]?[/] [bold]{rel_path}:{r.usage.line}[/] {r.usage.code}")
157
+ console.print(f" [dim]{r.change.description}[/]\n")
158
+
159
+ console.print(f"[green]{len(safe)}[/] other usages are safe.\n")
160
+
161
+ # summary
162
+ if breaking:
163
+ console.print(Panel(
164
+ f"[red bold]Upgrade risky.[/] {len(breaking)} breaking change(s) affect your code.",
165
+ border_style="red",
166
+ ))
167
+ elif deprecated:
168
+ console.print(Panel(
169
+ f"[yellow]Upgrade possible[/] but {len(deprecated)} deprecated API(s) should be updated.",
170
+ border_style="yellow",
171
+ ))
172
+
173
+
174
+ def _print_usages_summary(usages, package):
175
+ """Print a summary of found usages."""
176
+ console.print(f"\n[bold]Your usages of {package}:[/]")
177
+ apis = set()
178
+ for u in usages:
179
+ if u.usage_type != "import":
180
+ apis.add(u.attr_chain)
181
+ for api in sorted(apis):
182
+ console.print(f" {api}")
183
+
184
+
185
+ def _print_json(risks, safe, package, current, target_version):
186
+ """Print JSON output."""
187
+ import json
188
+ output = {
189
+ "package": package,
190
+ "current_version": current,
191
+ "target_version": target_version,
192
+ "risks": [
193
+ {
194
+ "file": r.usage.file,
195
+ "line": r.usage.line,
196
+ "code": r.usage.code,
197
+ "api": r.usage.attr_chain,
198
+ "severity": r.severity,
199
+ "change_kind": r.change.kind,
200
+ "change_description": r.change.description,
201
+ "change_version": r.change.version,
202
+ }
203
+ for r in risks
204
+ ],
205
+ "safe_count": len(safe),
206
+ "breaking_count": sum(1 for r in risks if r.severity == "breaking"),
207
+ "deprecated_count": sum(1 for r in risks if r.severity == "deprecated"),
208
+ }
209
+ console.print_json(json.dumps(output))
210
+
211
+
212
+ @main.command()
213
+ @click.argument("package")
214
+ def scan(package: str):
215
+ """Just scan your code for usages of PACKAGE (no upgrade check)."""
216
+ directory = os.path.abspath(".")
217
+
218
+ with console.status(f"Scanning for usages of [bold]{package}[/]..."):
219
+ usages = scan_directory(directory, package)
220
+
221
+ if not usages:
222
+ console.print(f"[yellow]No usages of {package} found.[/]")
223
+ sys.exit(0)
224
+
225
+ table = Table(title=f"Usages of {package}")
226
+ table.add_column("File", style="cyan")
227
+ table.add_column("Line", justify="right", style="green")
228
+ table.add_column("API", style="yellow")
229
+ table.add_column("Code", style="dim")
230
+
231
+ for u in usages:
232
+ rel_path = os.path.relpath(u.file)
233
+ table.add_row(rel_path, str(u.line), u.attr_chain, u.code[:80])
234
+
235
+ console.print(table)
236
+ console.print(f"\n[bold]{len(usages)}[/] usages across [bold]{len(set(u.file for u in usages))}[/] files.")
237
+
238
+
239
+ @main.command()
240
+ @click.argument("package")
241
+ def versions(package: str):
242
+ """List available versions for PACKAGE."""
243
+ with console.status(f"Fetching versions for [bold]{package}[/]..."):
244
+ try:
245
+ vers = get_available_versions(package)
246
+ except Exception as e:
247
+ console.print(f"[red]Error:[/] {e}")
248
+ sys.exit(1)
249
+
250
+ from packaging.version import Version, InvalidVersion
251
+ parsed = []
252
+ for v in vers:
253
+ try:
254
+ parsed.append(Version(v))
255
+ except InvalidVersion:
256
+ pass
257
+
258
+ parsed.sort(reverse=True)
259
+ latest_10 = parsed[:10]
260
+
261
+ console.print(f"[bold]{package}[/] latest versions:\n")
262
+ for v in latest_10:
263
+ console.print(f" {v}")
264
+ if len(parsed) > 10:
265
+ console.print(f"\n ...and {len(parsed) - 10} more")
266
+
267
+
268
+ if __name__ == "__main__":
269
+ main()
@@ -0,0 +1,148 @@
1
+ """Scan Python files for all usages of a given package."""
2
+
3
+ import ast
4
+ import os
5
+ from dataclasses import dataclass, field
6
+ from pathlib import Path
7
+ from typing import List, Optional, Set
8
+
9
+
10
+ @dataclass
11
+ class Usage:
12
+ """A single usage of a package in a file."""
13
+ file: str
14
+ line: int
15
+ code: str
16
+ attr_chain: str # e.g. "requests.get" or "requests.packages.urllib3"
17
+ usage_type: str # "import", "function_call", "attribute_access", "submodule"
18
+
19
+
20
+ class PackageVisitor(ast.NodeVisitor):
21
+ """Walk an AST and collect every reference to the target package."""
22
+
23
+ def __init__(self, package_name: str, source_lines: List[str], filepath: str):
24
+ self.package = package_name
25
+ self.lines = source_lines
26
+ self.filepath = filepath
27
+ self.usages: List[Usage] = []
28
+ self.aliases: dict[str, str] = {} # alias -> real dotted name
29
+ self.from_imports: dict[str, str] = {} # local name -> full dotted name
30
+
31
+ def visit_Import(self, node: ast.Import):
32
+ for alias in node.names:
33
+ if alias.name == self.package or alias.name.startswith(f"{self.package}."):
34
+ local = alias.asname or alias.name
35
+ self.aliases[local] = alias.name
36
+ self.usages.append(Usage(
37
+ file=self.filepath,
38
+ line=node.lineno,
39
+ code=self.lines[node.lineno - 1].strip(),
40
+ attr_chain=alias.name,
41
+ usage_type="import",
42
+ ))
43
+ self.generic_visit(node)
44
+
45
+ def visit_ImportFrom(self, node: ast.ImportFrom):
46
+ module = node.module or ""
47
+ if module == self.package or module.startswith(f"{self.package}."):
48
+ for alias in node.names:
49
+ local = alias.asname or alias.name
50
+ full = f"{module}.{alias.name}"
51
+ self.from_imports[local] = full
52
+ self.usages.append(Usage(
53
+ file=self.filepath,
54
+ line=node.lineno,
55
+ code=self.lines[node.lineno - 1].strip(),
56
+ attr_chain=full,
57
+ usage_type="import",
58
+ ))
59
+ self.generic_visit(node)
60
+
61
+ def visit_Attribute(self, node: ast.Attribute):
62
+ chain = self._resolve_attr_chain(node)
63
+ if chain and self._is_package_ref(chain):
64
+ self.usages.append(Usage(
65
+ file=self.filepath,
66
+ line=node.lineno,
67
+ code=self.lines[node.lineno - 1].strip(),
68
+ attr_chain=chain,
69
+ usage_type="attribute_access",
70
+ ))
71
+ self.generic_visit(node)
72
+
73
+ def visit_Call(self, node: ast.Call):
74
+ chain = self._resolve_attr_chain(node.func)
75
+ if chain and self._is_package_ref(chain):
76
+ self.usages.append(Usage(
77
+ file=self.filepath,
78
+ line=node.lineno,
79
+ code=self.lines[node.lineno - 1].strip(),
80
+ attr_chain=chain,
81
+ usage_type="function_call",
82
+ ))
83
+ self.generic_visit(node)
84
+
85
+ def _resolve_attr_chain(self, node) -> Optional[str]:
86
+ """Turn a nested Attribute node into a dotted string."""
87
+ parts = []
88
+ current = node
89
+ while isinstance(current, ast.Attribute):
90
+ parts.append(current.attr)
91
+ current = current.value
92
+ if isinstance(current, ast.Name):
93
+ parts.append(current.id)
94
+ parts.reverse()
95
+ name = parts[0]
96
+ rest = ".".join(parts[1:])
97
+ # resolve aliases
98
+ if name in self.aliases:
99
+ return f"{self.aliases[name]}.{rest}" if rest else self.aliases[name]
100
+ if name in self.from_imports:
101
+ return f"{self.from_imports[name]}.{rest}" if rest else self.from_imports[name]
102
+ if name == self.package:
103
+ return ".".join(parts)
104
+ return None
105
+
106
+ def _is_package_ref(self, chain: str) -> bool:
107
+ return chain == self.package or chain.startswith(f"{self.package}.")
108
+
109
+
110
+ def scan_file(filepath: str, package_name: str) -> List[Usage]:
111
+ """Scan a single Python file for usages of package_name."""
112
+ try:
113
+ with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
114
+ source = f.read()
115
+ lines = source.splitlines()
116
+ tree = ast.parse(source, filename=filepath)
117
+ except (SyntaxError, UnicodeDecodeError):
118
+ return []
119
+
120
+ visitor = PackageVisitor(package_name, lines, filepath)
121
+ visitor.visit(tree)
122
+
123
+ # dedupe by (file, line, attr_chain)
124
+ seen: Set[tuple] = set()
125
+ deduped: List[Usage] = []
126
+ for u in visitor.usages:
127
+ key = (u.file, u.line, u.attr_chain)
128
+ if key not in seen:
129
+ seen.add(key)
130
+ deduped.append(u)
131
+ return deduped
132
+
133
+
134
+ def scan_directory(directory: str, package_name: str, exclude_dirs: Optional[Set[str]] = None) -> List[Usage]:
135
+ """Recursively scan a directory for usages of package_name."""
136
+ if exclude_dirs is None:
137
+ exclude_dirs = {".venv", "venv", "env", ".env", "node_modules", "__pycache__",
138
+ ".git", ".tox", ".mypy_cache", ".pytest_cache", "dist", "build",
139
+ ".eggs", "*.egg-info"}
140
+
141
+ usages: List[Usage] = []
142
+ for root, dirs, files in os.walk(directory):
143
+ dirs[:] = [d for d in dirs if d not in exclude_dirs and not d.endswith(".egg-info")]
144
+ for fname in files:
145
+ if fname.endswith(".py"):
146
+ fpath = os.path.join(root, fname)
147
+ usages.extend(scan_file(fpath, package_name))
148
+ return usages
@@ -0,0 +1,35 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "pyupcheck"
7
+ version = "0.1.0"
8
+ description = "Check if upgrading a Python dependency will break your code"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.8"
12
+ authors = [{name = "AgbaDev"}]
13
+ keywords = ["cli", "dependency", "upgrade", "migration", "breaking-changes"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "Programming Language :: Python :: 3",
19
+ "Topic :: Software Development :: Quality Assurance",
20
+ ]
21
+ dependencies = [
22
+ "httpx>=0.24.0",
23
+ "rich>=13.0.0",
24
+ "click>=8.0.0",
25
+ ]
26
+
27
+ [project.scripts]
28
+ pyupcheck = "depshift.cli:main"
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/AgbaDev/pyupcheck"
32
+ Issues = "https://github.com/AgbaDev/pyupcheck/issues"
33
+
34
+ [tool.setuptools.packages.find]
35
+ include = ["depshift*"]
@@ -0,0 +1,116 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyupcheck
3
+ Version: 0.1.0
4
+ Summary: Check if upgrading a Python dependency will break your code
5
+ Author: AgbaDev
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/AgbaDev/pyupcheck
8
+ Project-URL: Issues, https://github.com/AgbaDev/pyupcheck/issues
9
+ Keywords: cli,dependency,upgrade,migration,breaking-changes
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development :: Quality Assurance
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: httpx>=0.24.0
19
+ Requires-Dist: rich>=13.0.0
20
+ Requires-Dist: click>=8.0.0
21
+ Dynamic: license-file
22
+
23
+ # pyupcheck
24
+
25
+ Check if upgrading a Python dependency will break your code.
26
+
27
+ ```
28
+ $ pyupcheck check requests 3.0.0
29
+
30
+ pyupcheck 2.31.0 -> 3.0.0
31
+
32
+ Found 14 usages across 5 files.
33
+ Found 3 potentially breaking/deprecated changes.
34
+
35
+ BREAKING (1):
36
+
37
+ x src/api.py:23 resp = requests.get(url, verify=False)
38
+ Removed: `verify` parameter no longer accepted
39
+
40
+ DEPRECATED (1):
41
+
42
+ ! src/utils.py:8 from requests.packages import urllib3
43
+ Deprecated: use `urllib3` directly instead
44
+
45
+ 12 other usages are safe.
46
+
47
+ ╭─ pyupcheck report ──────────────────────────────────╮
48
+ │ Upgrade risky. 1 breaking change(s) affect your │
49
+ │ code. │
50
+ ╰────────────────────────────────────────────────────╯
51
+ ```
52
+
53
+ ## Install
54
+
55
+ ```bash
56
+ pip install pyupcheck
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ ### Check an upgrade
62
+
63
+ ```bash
64
+ # check against a specific version
65
+ pyupcheck check flask 3.0.0
66
+
67
+ # check against the latest version
68
+ pyupcheck check flask
69
+
70
+ # scan a specific directory
71
+ pyupcheck check requests 3.0.0 --dir ./src
72
+
73
+ # json output for CI
74
+ pyupcheck check requests 3.0.0 --json-output
75
+ ```
76
+
77
+ Exit code is 1 if breaking changes are found, 0 otherwise. Use this in CI to gate upgrades.
78
+
79
+ ### Scan your code
80
+
81
+ ```bash
82
+ # just see what APIs you use from a package
83
+ pyupcheck scan requests
84
+ ```
85
+
86
+ ### List versions
87
+
88
+ ```bash
89
+ pyupcheck versions flask
90
+ ```
91
+
92
+ ## How it works
93
+
94
+ 1. Scans your `.py` files with AST parsing to find every import and usage of the target package
95
+ 2. Fetches the changelog from GitHub releases and PyPI metadata
96
+ 3. Parses the changelog for breaking changes, deprecations, and renames
97
+ 4. Cross-references your usage against the changes
98
+ 5. Reports which of your usages are at risk
99
+
100
+ ## Limitations
101
+
102
+ - Changelog parsing relies on maintainers writing structured changelogs. If a project has unstructured notes, pyupcheck may miss changes.
103
+ - Dynamic attribute access (`getattr(requests, method_name)`) is not detected.
104
+ - Only scans `.py` files (not Jupyter notebooks, config files, etc.)
105
+
106
+ ## Options
107
+
108
+ | Flag | Description |
109
+ |------|-------------|
110
+ | `--dir`, `-d` | Directory to scan (default: `.`) |
111
+ | `--github-token` | GitHub token for higher API rate limits (or set `GITHUB_TOKEN` env var) |
112
+ | `--json-output`, `-j` | Output as JSON |
113
+
114
+ ## License
115
+
116
+ MIT
@@ -0,0 +1,14 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ depshift/__init__.py
5
+ depshift/analyzer.py
6
+ depshift/changelog.py
7
+ depshift/cli.py
8
+ depshift/scanner.py
9
+ pyupcheck.egg-info/PKG-INFO
10
+ pyupcheck.egg-info/SOURCES.txt
11
+ pyupcheck.egg-info/dependency_links.txt
12
+ pyupcheck.egg-info/entry_points.txt
13
+ pyupcheck.egg-info/requires.txt
14
+ pyupcheck.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ pyupcheck = depshift.cli:main
@@ -0,0 +1,3 @@
1
+ httpx>=0.24.0
2
+ rich>=13.0.0
3
+ click>=8.0.0
@@ -0,0 +1 @@
1
+ depshift
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+