apkdiff-core 1.0.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,77 @@
1
+ Metadata-Version: 2.4
2
+ Name: apkdiff-core
3
+ Version: 1.0.0
4
+ Summary: APK size diff core library: attributes DEX bytes to classes, compares classes and resources, and renders console/JSON/HTML/Markdown reports
5
+ Author: Jayvin
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/Jayvinz/apkdiff
8
+ Project-URL: Repository, https://github.com/Jayvinz/apkdiff
9
+ Project-URL: Source, https://github.com/Jayvinz/apkdiff/tree/main/py
10
+ Keywords: apk,dex,android,size,diff,r8,proguard
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.7
17
+ Classifier: Programming Language :: Python :: 3.8
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Software Development :: Build Tools
25
+ Requires-Python: >=3.7
26
+ Description-Content-Type: text/markdown
27
+
28
+ [English](README.md) | [简体中文](README.zh-CN.md)
29
+
30
+ # apkdiff-core
31
+
32
+ APK size diff core library (pure Python standard library, zero runtime dependencies).
33
+
34
+ Attributes DEX bytes to classes, compares classes and resources between two APKs, and
35
+ renders console / JSON / HTML / Markdown reports.
36
+
37
+ ## Install
38
+
39
+ ```bash
40
+ pip install apkdiff-core
41
+ ```
42
+
43
+ Python 3.7 or newer.
44
+
45
+ ## Usage
46
+
47
+ ```python
48
+ from apkdiff_core import (
49
+ analyze_apk,
50
+ diff_apks,
51
+ load_mapping,
52
+ print_console,
53
+ write_html,
54
+ write_json,
55
+ write_markdown,
56
+ )
57
+
58
+ old = analyze_apk("old.apk", load_mapping("old/mapping.txt"))
59
+ new = analyze_apk("new.apk", load_mapping("new/mapping.txt"))
60
+ result = diff_apks(old, new, include_meta=False, detect_renames=True)
61
+
62
+ print_console(result, metric="compressed", top=30)
63
+ write_json(result, "report/apkdiff.json", "compressed")
64
+ write_html(result, "report/apkdiff.html", "compressed")
65
+ write_markdown(result, "report/apkdiff.md", "compressed")
66
+ ```
67
+
68
+ Public API:
69
+
70
+ - `analyze_apk(path, mapping=None, hash_content=True)`
71
+ - `load_mapping(path)` / `Mapping.parse(path)`
72
+ - `diff_apks(old, new, include_meta=False, detect_renames=False)`
73
+ - `print_console` / `build_json` / `write_json` / `write_html` / `write_markdown`
74
+ - `human_size` / `human_delta`
75
+ - data classes: `ApkAnalysis`, `ApkClass`, `ApkEntry`, `DexAnalysis`, `DexClass`, `Change`, `DiffResult`
76
+
77
+ Reports are byte-for-byte identical to the JVM and Node.js implementations.
@@ -0,0 +1,50 @@
1
+ [English](README.md) | [简体中文](README.zh-CN.md)
2
+
3
+ # apkdiff-core
4
+
5
+ APK size diff core library (pure Python standard library, zero runtime dependencies).
6
+
7
+ Attributes DEX bytes to classes, compares classes and resources between two APKs, and
8
+ renders console / JSON / HTML / Markdown reports.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pip install apkdiff-core
14
+ ```
15
+
16
+ Python 3.7 or newer.
17
+
18
+ ## Usage
19
+
20
+ ```python
21
+ from apkdiff_core import (
22
+ analyze_apk,
23
+ diff_apks,
24
+ load_mapping,
25
+ print_console,
26
+ write_html,
27
+ write_json,
28
+ write_markdown,
29
+ )
30
+
31
+ old = analyze_apk("old.apk", load_mapping("old/mapping.txt"))
32
+ new = analyze_apk("new.apk", load_mapping("new/mapping.txt"))
33
+ result = diff_apks(old, new, include_meta=False, detect_renames=True)
34
+
35
+ print_console(result, metric="compressed", top=30)
36
+ write_json(result, "report/apkdiff.json", "compressed")
37
+ write_html(result, "report/apkdiff.html", "compressed")
38
+ write_markdown(result, "report/apkdiff.md", "compressed")
39
+ ```
40
+
41
+ Public API:
42
+
43
+ - `analyze_apk(path, mapping=None, hash_content=True)`
44
+ - `load_mapping(path)` / `Mapping.parse(path)`
45
+ - `diff_apks(old, new, include_meta=False, detect_renames=False)`
46
+ - `print_console` / `build_json` / `write_json` / `write_html` / `write_markdown`
47
+ - `human_size` / `human_delta`
48
+ - data classes: `ApkAnalysis`, `ApkClass`, `ApkEntry`, `DexAnalysis`, `DexClass`, `Change`, `DiffResult`
49
+
50
+ Reports are byte-for-byte identical to the JVM and Node.js implementations.
@@ -0,0 +1,41 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "apkdiff-core"
7
+ dynamic = ["version"]
8
+ description = "APK size diff core library: attributes DEX bytes to classes, compares classes and resources, and renders console/JSON/HTML/Markdown reports"
9
+ readme = "README.md"
10
+ requires-python = ">=3.7"
11
+ license = { text = "Apache-2.0" }
12
+ authors = [{ name = "Jayvin" }]
13
+ keywords = ["apk", "dex", "android", "size", "diff", "r8", "proguard"]
14
+ classifiers = [
15
+ "Development Status :: 5 - Production/Stable",
16
+ "Intended Audience :: Developers",
17
+ "Operating System :: OS Independent",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3 :: Only",
20
+ "Programming Language :: Python :: 3.7",
21
+ "Programming Language :: Python :: 3.8",
22
+ "Programming Language :: Python :: 3.9",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Programming Language :: Python :: 3.14",
28
+ "Topic :: Software Development :: Build Tools",
29
+ ]
30
+ dependencies = []
31
+
32
+ [project.urls]
33
+ Homepage = "https://github.com/Jayvinz/apkdiff"
34
+ Repository = "https://github.com/Jayvinz/apkdiff"
35
+ Source = "https://github.com/Jayvinz/apkdiff/tree/main/py"
36
+
37
+ [tool.setuptools.packages.find]
38
+ where = ["src"]
39
+
40
+ [tool.setuptools.dynamic]
41
+ version = { attr = "apkdiff_core.__version__" }
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,80 @@
1
+ """apkdiff-core: core library for APK size diffs.
2
+
3
+ Compares two APKs, attributes DEX bytes to classes, computes added/deleted/
4
+ modified/renamed classes and resources with size changes, and renders console /
5
+ JSON / HTML / Markdown reports.
6
+
7
+ Typical usage:
8
+
9
+ from apkdiff_core import analyze_apk, load_mapping, diff_apks, print_console
10
+
11
+ old = analyze_apk("old.apk", load_mapping("old/mapping.txt"))
12
+ new = analyze_apk("new.apk", load_mapping("new/mapping.txt"))
13
+ result = diff_apks(old, new, detect_renames=True)
14
+ print_console(result)
15
+
16
+ No third-party runtime dependencies.
17
+ """
18
+
19
+ from .apk import ApkAnalysis, ApkClass, ApkEntry, analyze_apk, categorize
20
+ from .dex import (
21
+ DexAnalysis,
22
+ DexClass,
23
+ DexError,
24
+ DexFile,
25
+ descriptor_to_class_name,
26
+ )
27
+ from .diff import (
28
+ ADDED,
29
+ DELETED,
30
+ MODIFIED,
31
+ RENAMED,
32
+ STATUS_LABEL,
33
+ UNCHANGED,
34
+ Change,
35
+ DiffResult,
36
+ diff_apks,
37
+ )
38
+ from .mapping import Mapping, load_mapping
39
+ from .report import (
40
+ build_json,
41
+ print_console,
42
+ write_html,
43
+ write_json,
44
+ write_markdown,
45
+ )
46
+ from .util import SizeBreakdown, human_delta, human_size
47
+
48
+ __version__ = "1.0.0"
49
+
50
+ __all__ = [
51
+ "ADDED",
52
+ "ApkAnalysis",
53
+ "ApkClass",
54
+ "ApkEntry",
55
+ "Change",
56
+ "DELETED",
57
+ "DexAnalysis",
58
+ "DexClass",
59
+ "DexError",
60
+ "DexFile",
61
+ "DiffResult",
62
+ "MODIFIED",
63
+ "Mapping",
64
+ "RENAMED",
65
+ "STATUS_LABEL",
66
+ "SizeBreakdown",
67
+ "UNCHANGED",
68
+ "analyze_apk",
69
+ "build_json",
70
+ "categorize",
71
+ "descriptor_to_class_name",
72
+ "diff_apks",
73
+ "human_delta",
74
+ "human_size",
75
+ "load_mapping",
76
+ "print_console",
77
+ "write_html",
78
+ "write_json",
79
+ "write_markdown",
80
+ ]
@@ -0,0 +1,241 @@
1
+ """APK reader: unpack the APK, inventory its entries, and let dex.py analyze each dex.
2
+
3
+ An APK is a zip archive. This module does two things:
4
+
5
+ 1. Inventory resources: walk every zip entry, record its name, compressed and
6
+ uncompressed size, CRC and SHA-256, and classify it by path (res/, assets/,
7
+ lib/, META-INF/, resources.arsc, ...). Resource diffs use this inventory.
8
+
9
+ 2. Analyze code: find every classes*.dex, let dex.py attribute bytes to classes,
10
+ then map obfuscated class names back through the mapping file.
11
+
12
+ Compressed-size caveat:
13
+ A dex is compressed as one blob in the zip, so there is no exact way to slice
14
+ "the compressed bytes of one class". We estimate by applying the dex-wide
15
+ compression ratio (compressed size / uncompressed size) to each class's
16
+ uncompressed size. It is an estimate, but it reflects which class grew.
17
+
18
+ The default report metric (--metric compressed) uses this estimate.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import hashlib
24
+ import os
25
+ import posixpath
26
+ import re
27
+ import zipfile
28
+ from dataclasses import dataclass, field
29
+
30
+ from .dex import DexAnalysis, DexFile, descriptor_to_class_name
31
+ from .mapping import Mapping
32
+ from .util import SizeBreakdown
33
+
34
+ _DEX_RE = re.compile(r"^classes\d*\.dex$", re.IGNORECASE)
35
+
36
+
37
+ @dataclass
38
+ class ApkEntry:
39
+ name: str
40
+ category: str
41
+ compress_size: int
42
+ file_size: int
43
+ crc: int
44
+ sha256: str
45
+
46
+ @property
47
+ def is_resource(self) -> bool:
48
+ # META-INF is opt-in via --include-meta; the filtering happens in
49
+ # diff_apks(), so it must be included in the raw inventory here.
50
+ return self.category in (
51
+ "res", "assets", "resources", "manifest", "lib", "meta", "other"
52
+ )
53
+
54
+
55
+ @dataclass
56
+ class ApkClass:
57
+ name: str # deobfuscated when a mapping was supplied
58
+ raw_name: str # name as it appears in the dex
59
+ dex: str
60
+ size: int # uncompressed, attributed DEX bytes
61
+ compressed_size: int # estimated APK footprint contribution
62
+ breakdown: SizeBreakdown
63
+ content_hash: str
64
+ methods: int
65
+ fields: int
66
+ partial: bool = False
67
+ warning: str = ""
68
+
69
+ def as_dict(self) -> dict:
70
+ return {
71
+ "name": self.name,
72
+ "raw_name": self.raw_name,
73
+ "dex": self.dex,
74
+ "size": self.size,
75
+ "compressed_size": self.compressed_size,
76
+ "methods": self.methods,
77
+ "fields": self.fields,
78
+ "breakdown": self.breakdown.as_dict(),
79
+ "content_hash": self.content_hash,
80
+ }
81
+
82
+
83
+ @dataclass
84
+ class ApkAnalysis:
85
+ path: str
86
+ file_size: int
87
+ entries: dict[str, ApkEntry] = field(default_factory=dict)
88
+ classes: dict[str, ApkClass] = field(default_factory=dict)
89
+ dex_files: list[DexAnalysis] = field(default_factory=list)
90
+ warnings: list[str] = field(default_factory=list)
91
+
92
+ @property
93
+ def resource_entries(self) -> dict[str, ApkEntry]:
94
+ return {k: v for k, v in self.entries.items() if v.is_resource}
95
+
96
+ @property
97
+ def total_class_bytes(self) -> int:
98
+ return sum(c.size for c in self.classes.values())
99
+
100
+ @property
101
+ def total_class_compressed_bytes(self) -> int:
102
+ return sum(c.compressed_size for c in self.classes.values())
103
+
104
+ @property
105
+ def unattributed_dex_bytes(self) -> int:
106
+ return sum(d.unattributed for d in self.dex_files)
107
+
108
+
109
+ def categorize(name: str) -> str:
110
+ n = posixpath.normpath(name).replace("\\", "/")
111
+ if _DEX_RE.match(posixpath.basename(n)) and "/" not in n:
112
+ return "dex"
113
+ if n.startswith("res/"):
114
+ return "res"
115
+ if n.startswith("assets/"):
116
+ return "assets"
117
+ if n.startswith("lib/"):
118
+ return "lib"
119
+ if n.startswith("META-INF/"):
120
+ return "meta"
121
+ if n == "AndroidManifest.xml":
122
+ return "manifest"
123
+ if n == "resources.arsc":
124
+ return "resources"
125
+ return "other"
126
+
127
+
128
+ def analyze_apk(path: str, mapping: Mapping | None = None, hash_content: bool = True) -> ApkAnalysis:
129
+ """Read an APK and build the class / resource inventory."""
130
+ result = ApkAnalysis(path=path, file_size=0)
131
+ try:
132
+ result.file_size = os.stat(path).st_size
133
+ except OSError:
134
+ pass
135
+
136
+ try:
137
+ zf = zipfile.ZipFile(path, "r")
138
+ except (OSError, zipfile.BadZipFile) as exc:
139
+ result.warnings.append(f"cannot open APK: {exc}")
140
+ return result
141
+
142
+ with zf:
143
+ dex_contents: dict[str, bytes] = {}
144
+ infos = zf.infolist()
145
+ for info in infos:
146
+ if info.is_dir():
147
+ continue
148
+ name = info.filename.replace("\\", "/")
149
+ category = categorize(name)
150
+ digest = ""
151
+ if hash_content:
152
+ try:
153
+ if category == "dex":
154
+ # Read the dex once: hashing and analysis both need it.
155
+ content = zf.read(info)
156
+ digest = hashlib.sha256(content).hexdigest()
157
+ dex_contents[name] = content
158
+ else:
159
+ with zf.open(info, "r") as fh:
160
+ h = hashlib.sha256()
161
+ while True:
162
+ chunk = fh.read(1 << 20)
163
+ if not chunk:
164
+ break
165
+ h.update(chunk)
166
+ digest = h.hexdigest()
167
+ except Exception as exc: # noqa: BLE001
168
+ result.warnings.append(f"cannot hash {name}: {exc}")
169
+ result.entries[name] = ApkEntry(
170
+ name=name,
171
+ category=category,
172
+ compress_size=info.compress_size,
173
+ file_size=info.file_size,
174
+ crc=info.CRC,
175
+ sha256=digest,
176
+ )
177
+
178
+ # Analyze every classes*.dex
179
+ dex_names = sorted(
180
+ (n for n, e in result.entries.items() if e.category == "dex"),
181
+ key=_dex_sort_key,
182
+ )
183
+ for dex_name in dex_names:
184
+ try:
185
+ raw = dex_contents.get(dex_name)
186
+ if raw is None:
187
+ raw = zf.read(dex_name)
188
+ dex_analysis = DexFile(raw, dex_name=dex_name).analyze()
189
+ except Exception as exc: # noqa: BLE001
190
+ result.warnings.append(f"cannot analyze {dex_name}: {exc}")
191
+ continue
192
+ result.dex_files.append(dex_analysis)
193
+ result.warnings.extend(f"{dex_name}: {w}" for w in dex_analysis.warnings)
194
+
195
+ entry = result.entries[dex_name]
196
+ # Compressed class size is estimated: a dex is compressed as one blob,
197
+ # so we cannot slice per-class compressed bytes. Apply the dex-wide
198
+ # ratio (compressed / uncompressed) to each class's uncompressed size.
199
+ ratio = (entry.compress_size / entry.file_size) if entry.file_size else 0.0
200
+ for cls in dex_analysis.classes:
201
+ if mapping is not None:
202
+ display_name = mapping.deobfuscate_descriptor(cls.name)
203
+ else:
204
+ display_name = descriptor_to_class_name(cls.name)
205
+ est_compressed = int(round(cls.size * ratio))
206
+ existing = result.classes.get(display_name)
207
+ if existing is not None:
208
+ # A class can appear in multiple dex files (rare). Sum its sizes and
209
+ # combine hashes so it cannot silently disappear.
210
+ existing.size += cls.size
211
+ existing.compressed_size += est_compressed
212
+ existing.breakdown = existing.breakdown.plus(cls.breakdown)
213
+ existing.content_hash = hashlib.sha256(
214
+ (existing.content_hash + cls.content_hash).encode("ascii")
215
+ ).hexdigest()
216
+ existing.partial = existing.partial or cls.partial
217
+ existing.warning = " | ".join(filter(None, [existing.warning, cls.warning]))
218
+ else:
219
+ result.classes[display_name] = ApkClass(
220
+ name=display_name,
221
+ raw_name=descriptor_to_class_name(cls.name),
222
+ dex=dex_name,
223
+ size=cls.size,
224
+ compressed_size=est_compressed,
225
+ breakdown=cls.breakdown,
226
+ content_hash=cls.content_hash,
227
+ methods=cls.methods,
228
+ fields=cls.fields,
229
+ partial=cls.partial,
230
+ warning=cls.warning,
231
+ )
232
+
233
+ return result
234
+
235
+
236
+ def _dex_sort_key(name: str) -> tuple[int, str]:
237
+ base = posixpath.basename(name)
238
+ if base.lower() == "classes.dex":
239
+ return (0, name)
240
+ m = re.match(r"classes(\d+)\.dex$", base, re.IGNORECASE)
241
+ return (int(m.group(1)) if m else 9999, name)