pyflashkit 1.0.0__tar.gz

pyflashkit-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "LICENSE"
+      - ".gitignore"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "LICENSE"
+      - ".gitignore"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest -v

pyflashkit-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

pyflashkit-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+*.so
+.pytest_cache/

pyflashkit-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to flashkit
+
+## Setup
+
+```bash
+git clone <repo-url>
+cd flashkit
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+python -m pytest
+python -m pytest -v              # verbose
+python -m pytest tests/cli/      # just CLI tests
+python -m pytest -k "roundtrip"  # filter by name
+```
+
+## Project layout
+
+```
+flashkit/
+  cli/           CLI commands (one file per subcommand)
+  swf/           SWF container format
+  abc/           AVM2 bytecode parsing, writing, disassembly, builder
+  info/          Resolved class/field/method model
+  workspace/     File loading, resource management
+  analysis/      Inheritance, call graph, references, strings
+  search/        Unified query engine
+  errors.py      Error hierarchy
+
+tests/
+  abc/           ABC parser, writer, builder, disasm tests
+  swf/           SWF parser and builder tests
+  info/          ClassInfo resolution tests
+  workspace/     Workspace loading tests
+  analysis/      Analysis module tests
+  search/        Search engine tests
+  cli/           CLI integration tests
+  conftest.py    Shared fixtures (build_abc_bytes, build_swf_bytes)
+```
+
+## Writing tests
+
+All tests use programmatically built SWFs via `AbcBuilder` and `SwfBuilder` — no real `.swf` fixture files. This keeps the repo clean and tests fast.
+
+```python
+from flashkit.abc.builder import AbcBuilder
+from flashkit.abc.writer import serialize_abc
+from flashkit.swf.builder import SwfBuilder
+
+b = AbcBuilder()
+b.simple_class("Player", package="com.game", fields=[("hp", "int")])
+b.script()
+abc_bytes = serialize_abc(b.build())
+
+swf = SwfBuilder(version=40, width=800, height=600, fps=30)
+swf.add_abc("TestCode", abc_bytes)
+swf_bytes = swf.build()
+```
+
+## Adding a CLI command
+
+1. Create `flashkit/cli/mycommand.py`:
+
+```python
+"""``flashkit mycommand`` — description."""
+
+from __future__ import annotations
+import argparse
+from ._util import load, bold
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("mycommand", help="Short help text")
+    p.add_argument("file", help="SWF or SWZ file")
+    p.set_defaults(func=run)
+
+def run(args: argparse.Namespace) -> None:
+    ws = load(args.file)
+    # ...
+```
+
+2. Import and register it in `flashkit/cli/__init__.py`:
+
+```python
+from . import mycommand
+mycommand.register(sub)
+```
+
+3. Add tests in `tests/cli/test_cli.py`.
+
+## Pull requests
+
+1. Fork the repo and create a branch from `main`.
+2. If you added code, add tests. Run `python -m pytest` and make sure everything passes.
+3. Keep PRs focused — one feature or fix per PR.
+4. Use conventional commit messages for the PR title (`feat: add xyz`, `fix: handle edge case`).
+5. Describe **what** changed and **why** in the PR body. If it's a fix, link the issue.
+6. Make sure there are no type errors or lint warnings in the code you changed.
+
+## Conventions
+
+- **Zero dependencies.** Standard library only. No Click, no Rich, no Typer.
+- **Round-trip fidelity.** `serialize(parse(data)) == data` must hold for unmodified ABC.
+- **Conventional commits.** `feat:`, `fix:`, `test:`, `docs:`, `chore:`.
+- **Type hints everywhere.** All public functions and methods must have type annotations.
+- **No fixture files.** Tests build SWFs programmatically via `AbcBuilder` / `SwfBuilder`.
+- **One command per file.** CLI commands live in `flashkit/cli/`, one module each.
+- **Errors over silent failures.** Raise specific `FlashkitError` subclasses, never return `None` to signal failure in parsing code.
+
+## Error handling
+
+All public errors inherit from `FlashkitError`:
+
+```
+FlashkitError
+  ParseError
+    SWFParseError
+    ABCParseError
+  SerializeError
+  ResourceError
+```
+
+The CLI catches `FlashkitError` at the top level and prints a clean message. Don't let raw exceptions reach the user.

pyflashkit-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyflashkit-1.0.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: pyflashkit
+Version: 1.0.0
+Summary: SWF/ABC toolkit for parsing, analyzing, and manipulating Flash files and AVM2 bytecode
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# flashkit
+
+Parse, analyze, and manipulate Adobe Flash SWF files and AVM2 bytecode.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from flashkit.workspace import Workspace
+
+ws = Workspace()
+ws.load_swf("application.swf")
+
+# Find all classes extending Sprite
+for cls in ws.find_classes(extends="Sprite"):
+    print(f"{cls.qualified_name} — {len(cls.fields)} fields, {len(cls.methods)} methods")
+
+# Inspect a specific class
+player = ws.get_class("PlayerManager")
+print(player.super_name)    # "EventDispatcher"
+print(player.interfaces)    # ["IDisposable", "ITickable"]
+print(player.fields[0].name, player.fields[0].type_name)  # "mHealth", "Number"
+
+# Search strings used in bytecode
+from flashkit.analysis import StringIndex
+strings = StringIndex.from_workspace(ws)
+for s in strings.search("config"):
+    print(s)
+```
+
+---
+
+## CLI
+
+### `flashkit info`
+
+```
+$ flashkit info application.swf
+File: application.swf
+  Format:     SWF
+  SWF version: 40
+  Tags:       142
+  ABC blocks: 1
+  Classes:    823
+  Methods:    14210
+  Strings:    35482
+  Packages:   47
+```
+
+### `flashkit classes`
+
+```bash
+flashkit classes app.swf                # all classes
+flashkit classes app.swf -s Manager     # search by name
+flashkit classes app.swf -p com.game    # filter by package
+flashkit classes app.swf -e Sprite      # filter by superclass
+flashkit classes app.swf -i             # interfaces only
+flashkit classes app.swf -v             # verbose output
+```
+
+### `flashkit class`
+
+```
+$ flashkit class application.swf PlayerManager
+PlayerManager
+  Package: com.game
+  Extends: EventDispatcher
+  Implements: IDisposable, ITickable
+
+  Instance Fields (3)
+    mHealth: Number
+    mName: String
+    mLevel: int
+
+  Instance Methods (5)
+    init(): void
+    get name(): String
+    set name(value: String): void
+    takeDamage(amount: Number): void
+    serialize(): ByteArray
+```
+
+### `flashkit strings`
+
+```bash
+flashkit strings app.swf                # list all
+flashkit strings app.swf -s config      # search
+flashkit strings app.swf -s config -v   # with usage locations
+flashkit strings app.swf -s "\\d+" -r   # regex
+flashkit strings app.swf -c             # classify (URLs, debug)
+```
+
+### `flashkit tags`
+
+```bash
+flashkit tags app.swf
+```
+
+### `flashkit disasm`
+
+```bash
+flashkit disasm app.swf --class PlayerManager
+flashkit disasm app.swf --method-index 42
+```
+
+### `flashkit tree`
+
+```bash
+flashkit tree app.swf BaseEntity              # show descendants
+flashkit tree app.swf PlayerManager -a        # show ancestors
+```
+
+### `flashkit callers` / `flashkit callees`
+
+```bash
+flashkit callers app.swf toString
+flashkit callees app.swf PlayerManager.init
+```
+
+### `flashkit refs`
+
+```bash
+flashkit refs app.swf Point
+```
+
+### `flashkit packages` / `flashkit extract` / `flashkit build`
+
+```bash
+flashkit packages app.swf                     # list packages
+flashkit extract app.swf -o ./output          # extract ABC blocks
+flashkit build app.swf -o rebuilt.swf         # rebuild (compressed)
+flashkit build app.swf -o out.swf -d          # rebuild (decompressed)
+```
+
+---
+
+## Library
+
+### Load and query
+
+```python
+from flashkit.workspace import Workspace
+
+ws = Workspace()
+ws.load_swf("application.swf")
+ws.load_swz("module.swz")
+
+print(ws.summary())
+
+cls = ws.get_class("MyClass")
+print(cls.name, cls.super_name, cls.interfaces)
+print(cls.fields)   # list of FieldInfo
+print(cls.methods)  # list of MethodInfoResolved
+
+ws.find_classes(extends="Sprite")
+ws.find_classes(package="com.example", is_interface=True)
+```
+
+### Analysis
+
+```python
+from flashkit.analysis import InheritanceGraph, CallGraph, StringIndex
+
+graph = InheritanceGraph.from_classes(ws.classes)
+graph.get_children("BaseEntity")
+graph.get_all_parents("MyClass")
+graph.get_implementors("ISerializable")
+
+calls = CallGraph.from_workspace(ws)
+calls.get_callers("toString")
+calls.get_callees("MyClass.init")
+
+strings = StringIndex.from_workspace(ws)
+strings.search("config")
+strings.url_strings()
+strings.classes_using_string("http://example.com")
+```
+
+<details>
+<summary><strong>Parse SWF and ABC directly</strong></summary>
+
+```python
+from flashkit.swf import parse_swf, TAG_DO_ABC2
+from flashkit.abc import parse_abc, serialize_abc
+
+header, tags, version, length = parse_swf(swf_bytes)
+
+for tag in tags:
+    if tag.tag_type == TAG_DO_ABC2:
+        null_idx = tag.payload.index(0, 4)
+        abc = parse_abc(tag.payload[null_idx + 1:])
+        print(f"{len(abc.instances)} classes, {len(abc.methods)} methods")
+
+        # Round-trip fidelity: serialize(parse(data)) == data
+        assert serialize_abc(abc) == tag.payload[null_idx + 1:]
+```
+
+</details>
+
+<details>
+<summary><strong>Build SWF programmatically</strong></summary>
+
+```python
+from flashkit.abc import AbcBuilder, serialize_abc
+from flashkit.swf import SwfBuilder
+
+b = AbcBuilder()
+b.simple_class("Player", package="com.game",
+               fields=[("hp", "int"), ("name", "String")])
+b.script()
+abc_bytes = serialize_abc(b.build())
+
+swf = SwfBuilder(version=40, width=800, height=600, fps=30)
+swf.add_abc("GameCode", abc_bytes)
+swf_bytes = swf.build(compress=True)
+```
+
+</details>
+
+<details>
+<summary><strong>Disassemble method bodies</strong></summary>
+
+```python
+from flashkit.abc import decode_instructions
+
+for body in abc.method_bodies:
+    for instr in decode_instructions(body.code):
+        print(f"0x{instr.offset:04X}  {instr.mnemonic}  {instr.operands}")
+```
+
+</details>
+
+---
+
+## Project structure
+
+```
+flashkit/
+  cli/           CLI (one module per command)
+  swf/           SWF container (parse, build, tags)
+  abc/           AVM2 bytecode (parse, write, disasm, builder)
+  info/          Resolved class model (ClassInfo, FieldInfo, MethodInfo)
+  workspace/     File loading and class index
+  analysis/      Inheritance, call graph, references, strings
+  search/        Unified query engine
+```
+
+## References
+
+- [AVM2 Overview (Adobe)](https://www.adobe.com/content/dam/acom/en/devnet/pdf/avm2overview.pdf)
+- [SWF File Format Specification](https://open-flash.github.io/mirrors/swf-spec-19.pdf)
+
+## License
+
+MIT