pytecode 0.0.1__py3-none-any.whl

pytecode-0.0.1.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: pytecode
+Version: 0.0.1
+Summary: Python library for parsing, manipulating, and emitting JVM class files
+Author: Trenton Smith
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/smithtrenton/pytecode
+Project-URL: Documentation, https://smithtrenton.github.io/pytecode/
+Project-URL: Repository, https://github.com/smithtrenton/pytecode
+Project-URL: Issues, https://github.com/smithtrenton/pytecode/issues
+Project-URL: Changelog, https://github.com/smithtrenton/pytecode/releases
+Keywords: bytecode,classfile,java,jvm
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: basedpyright<2.0.0,>=1.38.3; extra == "dev"
+Requires-Dist: pdoc<17.0.0,>=16.0.0; extra == "dev"
+Requires-Dist: pytest<10.0.0,>=9.0.2; extra == "dev"
+Requires-Dist: ruff<0.16.0,>=0.15.7; extra == "dev"
+Dynamic: license-file
+
+# pytecode
+
+`pytecode` is a Python 3.14+ library for parsing, inspecting, editing, validating, and emitting JVM class files and JAR archives.
+
+It is built for Python tooling that needs direct access to Java bytecode: classfile readers and writers, archive rewriters, transformation pipelines, control-flow analysis, descriptor utilities, hierarchy-aware frame computation, and verification-oriented workflows.
+
+## Why pytecode?
+
+- Parse `.class` files into typed Python dataclasses.
+- Edit classes, fields, methods, and bytecode through a mutable symbolic model.
+- Rewrite JAR files while preserving non-class resources and ZIP metadata.
+- Recompute `max_stack`, `max_locals`, and `StackMapTable` when requested.
+- Validate parsed classfiles and edited models before emission.
+- Work with descriptors, signatures, labels, symbolic operands, constant pools, and debug-info policies.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install pytecode
+```
+
+Or with `uv`:
+
+```bash
+uv add pytecode
+```
+
+`pytecode` requires Python `3.14+`.
+
+## Quick start
+
+### Parse and roundtrip a class file
+
+```python
+from pathlib import Path
+
+from pytecode import ClassReader, ClassWriter
+
+reader = ClassReader.from_file("HelloWorld.class")
+classfile = reader.class_info
+
+print(classfile.major_version)
+print(classfile.methods_count)
+
+Path("HelloWorld-copy.class").write_bytes(ClassWriter.write(classfile))
+```
+
+### Lift to the editable model
+
+```python
+from pathlib import Path
+
+from pytecode import ClassModel
+
+model = ClassModel.from_bytes(Path("HelloWorld.class").read_bytes())
+print(model.name)
+
+updated_bytes = model.to_bytes()
+Path("HelloWorld-updated.class").write_bytes(updated_bytes)
+```
+
+Use `recompute_frames=True` when an edit changes control flow or stack/local layout.
+
+## JAR rewriting example
+
+`JarFile.rewrite()` can apply in-place transforms to matching classes and methods:
+
+```python
+from pytecode import JarFile
+from pytecode.constants import MethodAccessFlag
+from pytecode.model import ClassModel, MethodModel
+from pytecode.transforms import (
+    class_named,
+    method_is_public,
+    method_is_static,
+    method_name_matches,
+    on_methods,
+    pipeline,
+)
+
+
+def make_final(method: MethodModel, _owner: ClassModel) -> None:
+    method.access_flags |= MethodAccessFlag.FINAL
+
+
+JarFile("input.jar").rewrite(
+    "output.jar",
+    transform=pipeline(
+        on_methods(
+            make_final,
+            where=method_name_matches(r"main") & method_is_public() & method_is_static(),
+            owner=class_named("HelloWorld"),
+        )
+    ),
+)
+```
+
+Transforms must mutate models in place and return `None`. For code-shape changes, pass `recompute_frames=True`. For an ASM-like lift path that omits debug metadata, pass `skip_debug=True`.
+
+## Public surface
+
+Top-level exports:
+
+- `pytecode.ClassReader` and `pytecode.ClassWriter` for raw classfile parsing and emission.
+- `pytecode.JarFile` for archive reads, mutation, and safe rewrite-to-disk.
+- `pytecode.ClassModel` for mutable editing with symbolic references.
+
+Supported submodules:
+
+- `pytecode.transforms` for composable class, field, method, and code transforms.
+- `pytecode.labels` for label-aware bytecode editing helpers.
+- `pytecode.operands` for symbolic operand wrappers.
+- `pytecode.analysis` for CFG construction, frame simulation, and recomputation helpers.
+- `pytecode.verify` for structural validation and diagnostics.
+- `pytecode.hierarchy` for type and override resolution helpers.
+- `pytecode.descriptors` for JVM descriptors and generic signatures.
+- `pytecode.constant_pool_builder` for deterministic constant-pool construction.
+- `pytecode.modified_utf8` for JVM Modified UTF-8 encoding and decoding.
+- `pytecode.debug_info` for explicit debug-info preservation and stripping policies.
+
+## Documentation
+
+- Development docs overview: [docs/OVERVIEW.md](https://github.com/smithtrenton/pytecode/blob/master/docs/OVERVIEW.md)
+- Hosted API reference: <https://smithtrenton.github.io/pytecode/>
+
+## Development
+
+Create a local environment with development tools:
+
+```powershell
+uv sync --extra dev
+```
+
+Common checks:
+
+```powershell
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest -q
+uv run python tools\generate_api_docs.py --check
+```
+
+Generate local API reference HTML with:
+
+```powershell
+uv run python tools\generate_api_docs.py
+```
+
+Build source and wheel distributions locally:
+
+```powershell
+uv build
+```
+
+The `oracle`-marked CFG tests lazily cache ASM 9.7.1 test jars under `.pytest_cache\pytecode-oracle` and also honor manually seeded jars in `tests\resources\oracle\lib`. If `java`, `javac`, or the ASM jars are unavailable, that suite skips without failing the rest of the test run.
+
+## Release automation
+
+PyPI releases are published from GitHub Actions by pushing an immutable `v<version>` tag that matches `project.version` in `pyproject.toml`. The release workflow reruns validation on the tagged commit, builds both `sdist` and `wheel` with `uv build`, and publishes from the protected `pypi` environment via PyPI Trusted Publishing.
+
+Release procedure:
+
+```powershell
+# 1) bump project.version in pyproject.toml
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest -q
+uv run python tools\generate_api_docs.py --check
+
+git commit -am "Bump version to X.Y.Z"
+git push origin master
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+The release workflow rejects tags that do not match `project.version`. Treat release tags as immutable: if a tag or published artifact is wrong, bump to a new version and publish a new tag instead of force-pushing the old one. If the workflow fails before the publish step because of environment approval or a transient PyPI issue, rerun the workflow for the same tag instead of moving the tag.
+
+## Repository utilities
+
+`run.py` is a manual smoke-test helper that parses a JAR file, writes pretty-printed parsed class structures under `<jar parent>\output\<jar stem>\parsed\`, and writes class-model-derived rewritten `.class` files plus copied resources under `<jar parent>\output\<jar stem>\rewritten\`.
+
+Example:
+
+```powershell
+uv run python .\run.py .\path\to\input.jar
+```
+
+The script prints read, parse, lift, write, and rewrite timings plus class and resource counts to stdout.

pytecode-0.0.1.dist-info/RECORD

@@ -0,0 +1,27 @@
+pytecode/__init__.py,sha256=0WijlZ3llZ5PBPC9yFTLCi17uprAZa5HBjQPrk8OBIE,930
+pytecode/analysis.py,sha256=H8f2uElVeY_6jVUvcb9BW7pDtmiMKpKdvrT3ej4V1Vg,77641
+pytecode/attributes.py,sha256=M2p_Ni7fOx7XnYQXinOIfFItnbRHHC8Dded0tt1WxZ0,20592
+pytecode/bytes_utils.py,sha256=rmVczsgq-TI3EGPO2N1Go93eO04_G3RIPWxFiEsqoO0,5465
+pytecode/class_reader.py,sha256=7GFldG94gaszgjQ1NEh9UwbVW8qKQ-l438TRNBxCOVs,38670
+pytecode/class_writer.py,sha256=RvOtmUJRciKaJu4QJ_WvfEb3LE6ZCMMryvhPrCAA6Y0,24317
+pytecode/constant_pool.py,sha256=mSww_ZznLTe-PeADLfxFoIuphTLAbuNAr9OB8RPsPDc,4005
+pytecode/constant_pool_builder.py,sha256=zKebqffE8qObqsjK6FXtjCCEbhit-iIxPC40HecZxPU,31450
+pytecode/constants.py,sha256=b_1p13jtCbFixmBNytfX3pzHj7en9rMFnXu-33WTvhk,5409
+pytecode/debug_info.py,sha256=Yst0MNh39r4Z92PZ6foZXnv9NP2Ymyg76zFjb6jwZWs,9903
+pytecode/descriptors.py,sha256=0q6z5GbijYZOf8xMPTPjtCWIGAZK8C7f-F8r2xmFYD0,23556
+pytecode/hierarchy.py,sha256=SseaGtZnN1XKY68iEgrcJsgYLpjLCWVkRll-FyiDR9I,18380
+pytecode/info.py,sha256=CX_JAVcFX3Ps7j1kabPT1RERFpFwETe4vel39r8kU2w,4824
+pytecode/instructions.py,sha256=oK0yrNu60otwc98GifXgUO64fhhKEDvrWTPeUOIAJ4o,12538
+pytecode/jar.py,sha256=lERB0D60WSQIM7aepLtRQt1-Eaj51EXL6jUpnUYz04c,9923
+pytecode/labels.py,sha256=aFXz9s3uwK5UScLZAi3RLG4md1Wf5i_JN2U-Eh065HU,36235
+pytecode/model.py,sha256=OkSHCOhm4z0x1uFS7dfd0-pIiLL0jqUSUAuKOhFpbiU,34583
+pytecode/modified_utf8.py,sha256=bJ_xeJMurV70NmayMrO4ILeyimUGXrot6AsmVf87CVs,4801
+pytecode/operands.py,sha256=k_aTMgwVxRGBdVjY0Tv7JYRIIf_VwKwJh92U3AD_cd8,21320
+pytecode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytecode/transforms.py,sha256=FSxRjQHizHRdfRL06WUF-k_JZ8DX7I_ohno9EpXR0C4,27274
+pytecode/verify.py,sha256=Rt-GBoMlX9U4ei6NylVbbFZ15nKptCkgTbOqlwGZkM8,53086
+pytecode-0.0.1.dist-info/licenses/LICENSE,sha256=xcOCdQxGtsJL7y8NYaYJZnoZNcnvMejSkpBKAhvlUe4,1070
+pytecode-0.0.1.dist-info/METADATA,sha256=hl7hQjs3pCETvNiHwuAS7ALw88uI1WcDKa1nhztpC8Q,7382
+pytecode-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pytecode-0.0.1.dist-info/top_level.txt,sha256=L1TzD0q2abDDznp3W8eWNoHtZK_pH3oXoEHWf7Su1Sg,9
+pytecode-0.0.1.dist-info/RECORD,,

pytecode-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pytecode-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Trenton Smith
+
+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.

pytecode-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pytecode