ines-parser 1.2.1__tar.gz → 1.3.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.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025
3
+ Copyright (c) 2025-2026 Leonid Kabanov
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -0,0 +1,98 @@
1
+ Metadata-Version: 2.4
2
+ Name: ines-parser
3
+ Version: 1.3.0
4
+ Summary: Parse iNES/NES 2.0 ROM headers; CLI to scan, export, summarize, and split ROMs
5
+ Author: Leonid Kabanov
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ponchick/ines-parser
8
+ Project-URL: Documentation, https://github.com/ponchick/ines-parser#readme
9
+ Project-URL: Repository, https://github.com/ponchick/ines-parser.git
10
+ Project-URL: Issues, https://github.com/ponchick/ines-parser/issues
11
+ Project-URL: Changelog, https://github.com/ponchick/ines-parser/releases
12
+ Keywords: nes,ines,rom,parser,retro,gaming,emulation
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: Games/Entertainment
21
+ Classifier: Topic :: System :: Archiving
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Provides-Extra: archive
26
+ Requires-Dist: libarchive-c>=4.0; extra == "archive"
27
+ Dynamic: license-file
28
+
29
+ # iNES Parser
30
+
31
+ Python library and CLI for NES ROMs in iNES / NES 2.0 format: parse headers, scan collections, export reports, summarize mappers, and split PRG/CHR. Requires Python 3.10+.
32
+
33
+ ```bash
34
+ pip install ines-parser
35
+ pip install "ines-parser[archive]" # optional: .7z / .zip / .rar
36
+ ```
37
+
38
+ ## CLI
39
+
40
+ After install the tools are on your `PATH`. From a checkout:
41
+
42
+ ```bash
43
+ ines_scan_roms.py /path/to/roms
44
+ # or: python -m ines_parser.cli.ines_scan_roms /path/to/roms
45
+ ```
46
+
47
+ Same idea for `ines_rom_stats.py` and `ines_split_rom.py`.
48
+
49
+ ### Scan
50
+
51
+ ```bash
52
+ ines_scan_roms.py /path/to/roms
53
+ ines_scan_roms.py /a /b --mapper 4 --show-all
54
+ ines_scan_roms.py /path/to/roms --format csv -o roms.csv
55
+ ines_scan_roms.py /path/to/roms --format csv -d ';' -o roms.csv
56
+ ines_scan_roms.py /path/to/roms --format csv --show-all -o roms-full.csv
57
+ ```
58
+
59
+ Filters: `--mapper`, `--mirroring H|V|F`, `--has-trainer`, `--min-prg` / `--max-prg`, `--min-chr` / `--max-chr` (KiB).
60
+
61
+ `--format text|html|csv|json` (default text). `-o` writes to a file. `--show-all` adds full header fields. For CSV, `-d` / `--delimiter` sets the separator (default `,`; use `;` for Excel with Russian locale, `tab` for TSV-style).
62
+
63
+ ### Stats
64
+
65
+ ```bash
66
+ ines_rom_stats.py /path/to/roms
67
+ ines_rom_stats.py /path/to/roms --json
68
+ ```
69
+
70
+ ### Split
71
+
72
+ ```bash
73
+ ines_split_rom.py game.nes
74
+ ines_split_rom.py roms.7z # prompts before overwrite; use --force to skip
75
+ ```
76
+
77
+ ## Library
78
+
79
+ ```python
80
+ from ines_parser import parse_ines_header
81
+
82
+ with open("game.nes", "rb") as f:
83
+ header = parse_ines_header(f.read(16))
84
+
85
+ if header and header.is_valid():
86
+ print(header)
87
+ print(header.detailed_str())
88
+ ```
89
+
90
+ ## Docs
91
+
92
+ - `docs/iNES.md`
93
+ - [NESdev iNES](https://www.nesdev.org/wiki/INES)
94
+ - [NESdev NES 2.0](https://www.nesdev.org/wiki/NES_2.0)
95
+
96
+ ## License
97
+
98
+ MIT — see `LICENSE`.
@@ -0,0 +1,70 @@
1
+ # iNES Parser
2
+
3
+ Python library and CLI for NES ROMs in iNES / NES 2.0 format: parse headers, scan collections, export reports, summarize mappers, and split PRG/CHR. Requires Python 3.10+.
4
+
5
+ ```bash
6
+ pip install ines-parser
7
+ pip install "ines-parser[archive]" # optional: .7z / .zip / .rar
8
+ ```
9
+
10
+ ## CLI
11
+
12
+ After install the tools are on your `PATH`. From a checkout:
13
+
14
+ ```bash
15
+ ines_scan_roms.py /path/to/roms
16
+ # or: python -m ines_parser.cli.ines_scan_roms /path/to/roms
17
+ ```
18
+
19
+ Same idea for `ines_rom_stats.py` and `ines_split_rom.py`.
20
+
21
+ ### Scan
22
+
23
+ ```bash
24
+ ines_scan_roms.py /path/to/roms
25
+ ines_scan_roms.py /a /b --mapper 4 --show-all
26
+ ines_scan_roms.py /path/to/roms --format csv -o roms.csv
27
+ ines_scan_roms.py /path/to/roms --format csv -d ';' -o roms.csv
28
+ ines_scan_roms.py /path/to/roms --format csv --show-all -o roms-full.csv
29
+ ```
30
+
31
+ Filters: `--mapper`, `--mirroring H|V|F`, `--has-trainer`, `--min-prg` / `--max-prg`, `--min-chr` / `--max-chr` (KiB).
32
+
33
+ `--format text|html|csv|json` (default text). `-o` writes to a file. `--show-all` adds full header fields. For CSV, `-d` / `--delimiter` sets the separator (default `,`; use `;` for Excel with Russian locale, `tab` for TSV-style).
34
+
35
+ ### Stats
36
+
37
+ ```bash
38
+ ines_rom_stats.py /path/to/roms
39
+ ines_rom_stats.py /path/to/roms --json
40
+ ```
41
+
42
+ ### Split
43
+
44
+ ```bash
45
+ ines_split_rom.py game.nes
46
+ ines_split_rom.py roms.7z # prompts before overwrite; use --force to skip
47
+ ```
48
+
49
+ ## Library
50
+
51
+ ```python
52
+ from ines_parser import parse_ines_header
53
+
54
+ with open("game.nes", "rb") as f:
55
+ header = parse_ines_header(f.read(16))
56
+
57
+ if header and header.is_valid():
58
+ print(header)
59
+ print(header.detailed_str())
60
+ ```
61
+
62
+ ## Docs
63
+
64
+ - `docs/iNES.md`
65
+ - [NESdev iNES](https://www.nesdev.org/wiki/INES)
66
+ - [NESdev NES 2.0](https://www.nesdev.org/wiki/NES_2.0)
67
+
68
+ ## License
69
+
70
+ MIT — see `LICENSE`.
@@ -25,7 +25,7 @@ from .mappers import (
25
25
  is_known_mapper,
26
26
  )
27
27
 
28
- __version__ = "1.2.1"
28
+ __version__ = "1.3.0"
29
29
  __author__ = "Leonid Kabanov"
30
30
  __all__ = [
31
31
  "parse_ines_header",
@@ -0,0 +1,253 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Aggregate statistics for iNES ROMs found under directories (and inside archives when libarchive is installed).
4
+
5
+ Currently reports counts per mapper number; the JSON output shape is intended to grow with more metrics later.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import json
12
+ import sys
13
+ from collections import Counter
14
+ from dataclasses import dataclass, field
15
+ from pathlib import Path
16
+ from typing import Any, Literal
17
+
18
+ sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
19
+
20
+ try:
21
+ import libarchive
22
+ except ImportError:
23
+ libarchive = None # type: ignore
24
+
25
+ from ines_parser import INES_HEADER_SIZE, parse_ines_header
26
+ from ines_parser.mappers import get_mapper_name
27
+
28
+ from ines_parser.cli.rom_fs import (
29
+ ALL_ARCHIVE_FORMATS,
30
+ ARCHIVE_EXTENSIONS,
31
+ LIBARCHIVE_AVAILABLE,
32
+ DEFAULT_ARCHIVE_PATH,
33
+ SUPPORTED_EXTENSIONS,
34
+ collect_supported_files,
35
+ read_header_from_blocks,
36
+ )
37
+
38
+
39
+ @dataclass
40
+ class RomStats:
41
+ """Counters for one stats run (possibly spanning multiple root directories)."""
42
+
43
+ mapper_counts: Counter = field(default_factory=Counter)
44
+ too_short: int = 0
45
+ parse_failed: int = 0
46
+ invalid_format: int = 0
47
+ read_error: int = 0
48
+
49
+ def record_header_bytes(self, header_bytes: bytes | None) -> None:
50
+ if header_bytes is None or len(header_bytes) < INES_HEADER_SIZE:
51
+ self.too_short += 1
52
+ return
53
+ header = parse_ines_header(header_bytes)
54
+ if header is None:
55
+ self.parse_failed += 1
56
+ return
57
+ if not header.is_valid():
58
+ self.invalid_format += 1
59
+ return
60
+ self.mapper_counts[header.mapper] += 1
61
+
62
+ @property
63
+ def valid_images(self) -> int:
64
+ return int(sum(self.mapper_counts.values()))
65
+
66
+
67
+ def tally_nes_file(file_path: Path, stats: RomStats) -> None:
68
+ try:
69
+ with open(file_path, "rb") as f:
70
+ stats.record_header_bytes(f.read(INES_HEADER_SIZE))
71
+ except OSError:
72
+ stats.read_error += 1
73
+
74
+
75
+ def tally_archive(archive_path: Path, stats: RomStats) -> None:
76
+ if not LIBARCHIVE_AVAILABLE or libarchive is None:
77
+ return
78
+ try:
79
+ with open(archive_path, "rb") as f:
80
+ with libarchive.fd_reader(f.fileno()) as archive:
81
+ for entry in archive:
82
+ if not entry.isfile:
83
+ continue
84
+ if not entry.name.lower().endswith(".nes"):
85
+ continue
86
+ stats.record_header_bytes(read_header_from_blocks(entry))
87
+ except OSError:
88
+ stats.read_error += 1
89
+ except Exception:
90
+ stats.read_error += 1
91
+
92
+
93
+ def tally_file(file_path: Path, stats: RomStats) -> None:
94
+ ext = file_path.suffix.lower()
95
+ if ext == ".nes":
96
+ tally_nes_file(file_path, stats)
97
+ elif ext in ARCHIVE_EXTENSIONS:
98
+ tally_archive(file_path, stats)
99
+
100
+
101
+ def tally_directory(directory: Path, stats: RomStats) -> None:
102
+ try:
103
+ paths = collect_supported_files(directory)
104
+ for path in paths:
105
+ tally_file(path, stats)
106
+ except KeyboardInterrupt:
107
+ print("\n\nInterrupted by user", file=sys.stderr)
108
+ raise
109
+
110
+
111
+ def build_report(
112
+ stats: RomStats,
113
+ sort: Literal["count", "mapper"],
114
+ directories: list[str],
115
+ ) -> dict[str, Any]:
116
+ rows: list[dict[str, Any]] = []
117
+ for mapper, count in stats.mapper_counts.items():
118
+ rows.append(
119
+ {
120
+ "mapper": mapper,
121
+ "name": get_mapper_name(mapper),
122
+ "count": count,
123
+ }
124
+ )
125
+ if sort == "count":
126
+ rows.sort(key=lambda r: (-r["count"], r["mapper"]))
127
+ else:
128
+ rows.sort(key=lambda r: r["mapper"])
129
+
130
+ return {
131
+ "schema_version": 1,
132
+ "directories": directories,
133
+ "totals": {
134
+ "valid_images": stats.valid_images,
135
+ "skipped_too_short": stats.too_short,
136
+ "skipped_parse_failed": stats.parse_failed,
137
+ "skipped_invalid_format": stats.invalid_format,
138
+ "skipped_read_error": stats.read_error,
139
+ },
140
+ "by_mapper": rows,
141
+ }
142
+
143
+
144
+ def print_text_report(report: dict[str, Any]) -> None:
145
+ totals = report["totals"]
146
+ rows = report["by_mapper"]
147
+ print(
148
+ f"Directories: {', '.join(report['directories'])}\n"
149
+ f"Valid iNES images counted: {totals['valid_images']}\n"
150
+ f"Skipped - too short: {totals['skipped_too_short']}, "
151
+ f"parse failed: {totals['skipped_parse_failed']}, "
152
+ f"invalid format: {totals['skipped_invalid_format']}, "
153
+ f"read/archive error: {totals['skipped_read_error']}\n"
154
+ )
155
+ if not rows:
156
+ print("No valid ROM headers found.")
157
+ return
158
+ print(f"{'Mapper':>8} {'Count':>8} Name")
159
+ print(f"{'-' * 8} {'-' * 8} {'-' * 40}")
160
+ for r in rows:
161
+ print(f"{r['mapper']:>8} {r['count']:>8} {r['name']}")
162
+
163
+
164
+ def build_argument_parser() -> argparse.ArgumentParser:
165
+ supported = ", ".join(sorted(SUPPORTED_EXTENSIONS))
166
+ if not LIBARCHIVE_AVAILABLE:
167
+ supported += " (libarchive not installed — archive members not scanned)"
168
+
169
+ parser = argparse.ArgumentParser(
170
+ prog="ines_rom_stats.py",
171
+ description="Statistics for iNES ROMs under one or more directories",
172
+ formatter_class=argparse.RawDescriptionHelpFormatter,
173
+ epilog=f"Supported file types: {supported}",
174
+ )
175
+ parser.add_argument(
176
+ "directories",
177
+ nargs="*",
178
+ default=[DEFAULT_ARCHIVE_PATH],
179
+ metavar="DIR",
180
+ help=(
181
+ "Directories to scan recursively (includes archives as containers when supported); "
182
+ f"default if omitted: {DEFAULT_ARCHIVE_PATH}"
183
+ ),
184
+ )
185
+ parser.add_argument(
186
+ "--sort",
187
+ choices=("count", "mapper"),
188
+ default="count",
189
+ help="Sort breakdown by descending count or by mapper number (default: count)",
190
+ )
191
+ parser.add_argument(
192
+ "--json",
193
+ action="store_true",
194
+ help="Print machine-readable JSON (includes fields suitable for future extensions)",
195
+ )
196
+ parser.add_argument(
197
+ "--verbose",
198
+ "-v",
199
+ action="store_true",
200
+ help="Log scan roots and extension list to stderr",
201
+ )
202
+ return parser
203
+
204
+
205
+ def main() -> int:
206
+ parser = build_argument_parser()
207
+ args = parser.parse_args()
208
+
209
+ scan_roots: list[Path] = []
210
+ display_dirs: list[str] = []
211
+ for raw in args.directories:
212
+ p = Path(raw)
213
+ if not p.exists():
214
+ print(f"Error: Directory does not exist: {raw}", file=sys.stderr)
215
+ parser.print_help()
216
+ return 1
217
+ if not p.is_dir():
218
+ print(f"Error: Not a directory: {raw}", file=sys.stderr)
219
+ parser.print_help()
220
+ return 1
221
+ scan_roots.append(p)
222
+ display_dirs.append(raw)
223
+
224
+ if args.verbose:
225
+ print(f"Scanning {len(scan_roots)} root(s):", file=sys.stderr)
226
+ for r in scan_roots:
227
+ print(f" {r}", file=sys.stderr)
228
+ print(f"Extensions: {', '.join(sorted(SUPPORTED_EXTENSIONS))}", file=sys.stderr)
229
+ if not LIBARCHIVE_AVAILABLE:
230
+ print(
231
+ f"Note: without libarchive, archives {sorted(ALL_ARCHIVE_FORMATS)} are ignored.",
232
+ file=sys.stderr,
233
+ )
234
+
235
+ stats = RomStats()
236
+ try:
237
+ for root in scan_roots:
238
+ tally_directory(root, stats)
239
+ except KeyboardInterrupt:
240
+ return 130
241
+
242
+ report = build_report(stats, args.sort, display_dirs)
243
+
244
+ if args.json:
245
+ print(json.dumps(report, indent=2))
246
+ else:
247
+ print_text_report(report)
248
+
249
+ return 0
250
+
251
+
252
+ if __name__ == "__main__":
253
+ sys.exit(main())