Metadata-Version: 2.4
Name: py-cdec
Version: 0.1.0
Summary: Strong best-effort Python bytecode, marshal, and source analyzer/decompiler
Author: Ahmed Al-Hrani
License: MIT
Keywords: python,pyc,decompiler,marshal,bytecode
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: autopep8>=2.3.2
Dynamic: license-file

# py-cdec

Strong best-effort Python `.pyc`, marshal, and source analyzer/decompiler.

---

## Overview

`py-cdec` is a Python tool designed to analyze and decompile Python bytecode (`.pyc`) files and marshal payloads into readable Python-like source code.

It uses heuristic-based reconstruction techniques to recover structure, functions, and readable output from compiled Python artifacts.

This tool is useful for:
- Reverse engineering Python bytecode
- Learning how Python compilers structure code
- Inspecting unknown `.pyc` files
- Debugging compiled Python modules
- Educational analysis of Python internals

---

## Features

- Automatic detection of `.py` and `.pyc` files
- Bytecode disassembly support
- Marshal payload extraction and inspection
- Heuristic-based source reconstruction
- Recursive code object analysis
- CLI interface for quick usage
- Lightweight and dependency-free design

---

## Installation

Install via pip:

```bash
pip install py-cdec
```

Or install locally:

```bash
git clone https://github.com/Gisnsl/py-cdec.git
cd py-cdec
pip install .
```

---

## Usage (Python API)

You can use `py-cdec` directly inside your Python code.

```python
from pathlib import Path
from py_cdec import PycDecompiler

# Automatically handles both .pyc and .py files
pyc_path = Path("myfile.pyc")  # or myfile.py

decompiler = PycDecompiler(pyc_path)

# Print the decompiled source code directly
print(decompiler)
```

---

## Usage (CLI)

Run directly from terminal:

```bash
py-cdec sample.pyc
```

---

## Show Disassembly

To view Python bytecode instructions:

```bash
py-cdec sample.pyc --show-dis
```

---

## How It Works

`py-cdec` internally performs several steps:

1. **File Detection**
   - Detects whether the input is `.py` or `.pyc`

2. **Header Parsing**
   - Reads Python bytecode headers safely depending on version

3. **Marshal Loading**
   - Extracts compiled code objects using Python's marshal module

4. **Disassembly**
   - Converts bytecode into readable instructions

5. **Reconstruction**
   - Attempts to rebuild Python-like source using heuristics

6. **Output Formatting**
   - Produces readable structured output

---

## Project Goals

The main goal of `py-cdec` is not perfect decompilation, but:

- Producing readable reconstructed code
- Helping developers understand compiled Python internals
- Providing a safe inspection tool for bytecode analysis

---

## Security Notice

âڑ ï¸ڈ WARNING:

Never execute unknown `.pyc` or marshal payloads directly.

They may contain malicious code even if they appear safe.

Always inspect before execution.

---

## Telegram Contact

Developer: @maho_s9

---

## License

MIT License
