Pkg.PYC — API for parsing Python compiled bytecode files

Overview

The Pkg.PYC module contains the API for parsing Python compiled bytecode files.

Disassembling PYC Bytecode File

The following code example demonstrates how to disassemble a Python bytecode file:

from Pro.Core import *
from Pkg.PYC import *

def disassemblePYC(fname):
    c = createContainerFromFile(fname)
    c.isNull()
    if c.isNull():
        return
    obj = PYCObject()
    if not obj.Load(c) or not obj.Parse():
        return
    out = NTTextBuffer()
    obj.Disassemble(out)
    print(out.buffer)

Module API

Pkg.PYC module API.

Attributes:

OBJECT_FLAG_REF	Reference flag for object types.
OBJECT_TYPE_ASCII	ASCII string object type.
OBJECT_TYPE_ASCII_INTERNED	Interned ASCII string object type.
OBJECT_TYPE_BINARY_COMPLEX	Binary complex object type.
OBJECT_TYPE_BINARY_FLOAT	Binary float object type.
OBJECT_TYPE_CODE	Code object type.
OBJECT_TYPE_CODE_10_12	Code object type.
OBJECT_TYPE_COMPLEX	Complex object type.
OBJECT_TYPE_DICT	Dictionary object type.
OBJECT_TYPE_ELLIPSIS	Ellipsis object type.
OBJECT_TYPE_FALSE	False object type.
OBJECT_TYPE_FLOAT	Float object type.
OBJECT_TYPE_FROZENSET	FrozenSet object type.
OBJECT_TYPE_INT	Integer object type.
OBJECT_TYPE_INT64	64-bit integer object type.
OBJECT_TYPE_INTERNED	Interned object type.
OBJECT_TYPE_LIST	List object type.
OBJECT_TYPE_LONG	Long object type.
OBJECT_TYPE_NONE	None object type.
OBJECT_TYPE_NULL	Null object type.
OBJECT_TYPE_REF	Type reference object type.
OBJECT_TYPE_SET	Set object type.
OBJECT_TYPE_SHORT_ASCII	Short ASCII string object type.
OBJECT_TYPE_SHORT_ASCII_INTERNED	Interned short ASCII string object type.
OBJECT_TYPE_SMALL_TUPLE	Small tuple object type.
OBJECT_TYPE_STOPITER	StopIter object type.
OBJECT_TYPE_STRING	String object type.
OBJECT_TYPE_STRINGREF	String reference object type.
OBJECT_TYPE_TRUE	True object type.
OBJECT_TYPE_TUPLE	Tuple object type.
OBJECT_TYPE_UNICODE	Unicode string object type.
OBJECT_TYPE_UNKNOWN	Unknown object type.

Classes:

PYCObject()	This class represents a Python compiled bytecode file.
PyCComplex()	This class represents a Python Binary Complex object (OBJECT_TYPE_BINARY_COMPLEX).
PyCFloat()	This class represents a Python Binary Float object (OBJECT_TYPE_BINARY_FLOAT).
PyCode()	This class represents a Python Code object (e.g., OBJECT_TYPE_CODE).
PyComplex()	This class represents a Python Complex object (OBJECT_TYPE_COMPLEX).
PyDict()	This class represents a Python Dictionary object (OBJECT_TYPE_DICT).
PyEllipsis()	This class represents a Python Ellipsis object (OBJECT_TYPE_ELLIPSIS).
PyFalse()	This class represents a Python False object (OBJECT_TYPE_FALSE).
PyFloat()	This class represents a Python Float object (OBJECT_TYPE_FLOAT).
PyInt()	This class represents a Python Integer object (e.g., OBJECT_TYPE_INT).
PyList()	This class represents a Python List object (OBJECT_TYPE_LIST).
PyLong()	This class represents a Python Long object (e.g., OBJECT_TYPE_LONG).
PyNone()	This class represents a Python None object (OBJECT_TYPE_NONE).
PyNull()	This class represents a Python Null object (OBJECT_TYPE_NULL).
PyObject()	This class represents the base class for every Python object.
PySet()	This class represents a Python Set object (OBJECT_TYPE_SET).
PyStopIter()	This class represents a Python StopIter object (OBJECT_TYPE_STOPITER).
PyString()	This class represents a Python String object (e.g., OBJECT_TYPE_STRING).
PyTrue()	This class represents a Python True object (OBJECT_TYPE_TRUE).
PyTuple()	This class represents a Python Tuple object (e.g., OBJECT_TYPE_TUPLE).

OBJECT_FLAG_REF

Reference flag for object types.

OBJECT_TYPE_ASCII

ASCII string object type.

OBJECT_TYPE_ASCII_INTERNED

Interned ASCII string object type.

OBJECT_TYPE_BINARY_COMPLEX

Binary complex object type.

OBJECT_TYPE_BINARY_FLOAT

Binary float object type.

OBJECT_TYPE_CODE

Code object type.

OBJECT_TYPE_CODE_10_12

Code object type.

OBJECT_TYPE_COMPLEX

Complex object type.

OBJECT_TYPE_DICT

Dictionary object type.

OBJECT_TYPE_ELLIPSIS

Ellipsis object type.

OBJECT_TYPE_FALSE

False object type.

OBJECT_TYPE_FLOAT

Float object type.

OBJECT_TYPE_FROZENSET

FrozenSet object type.

OBJECT_TYPE_INT

Integer object type.

OBJECT_TYPE_INT64

64-bit integer object type.

OBJECT_TYPE_INTERNED

Interned object type.

OBJECT_TYPE_LIST

List object type.

OBJECT_TYPE_LONG

Long object type.

OBJECT_TYPE_NONE

None object type.

OBJECT_TYPE_NULL

Null object type.

OBJECT_TYPE_REF

Type reference object type.

OBJECT_TYPE_SET

Set object type.

OBJECT_TYPE_SHORT_ASCII

Short ASCII string object type.

OBJECT_TYPE_SHORT_ASCII_INTERNED

Interned short ASCII string object type.

OBJECT_TYPE_SMALL_TUPLE

Small tuple object type.

OBJECT_TYPE_STOPITER

StopIter object type.

OBJECT_TYPE_STRING

String object type.

OBJECT_TYPE_STRINGREF

String reference object type.

OBJECT_TYPE_TRUE

True object type.

OBJECT_TYPE_TUPLE

Tuple object type.

OBJECT_TYPE_UNICODE

Unicode string object type.

OBJECT_TYPE_UNKNOWN

Unknown object type.

class PYCObject

Bases: Pro.Core.CFFObject

This class represents a Python compiled bytecode file.

Methods:

CreateModuleHeaderFromMagic(magic)	Computes the module header by specifying the Python’s magic signature.
CreateModuleHeaderFromVersion(major_version, …)	Computes the module header by specifying the major and minor version of Python.
Disassemble(out)	Disassembles the entire file.
DisassembleCode(out, code_obj)	Disassembles a specific code object.
GetEndOffset()	Returns the computed end offset of the PYC file.
GetModuleFileName()	Returns the module file name if available; otherwise returns None.
GetObjectMap()	Returns the object tree as a map.
GetObjectTree()	Returns the root object of the tree.
GetVersion()	Returns the Python major and minor version of the PYC file as a tuple.
Parse([wo, verbose])	Parses the format.

static CreateModuleHeaderFromMagic(magic: int)

Computes the module header by specifying the Python’s magic signature.

Parameters

magic (int) – The magic signature.

Returns

Returns the computed header if successful; otherwise returns None.

Return type

Optional[bytes]

See also CreateModuleHeaderFromVersion().

static CreateModuleHeaderFromVersion(major_version: int, minor_version: int) → Optional[bytes]

Computes the module header by specifying the major and minor version of Python.

Parameters

• major_version (int) – The major version of Python.

• minor_version (int) – The minor version of Python.

Returns

Returns the computed header if successful; otherwise returns None.

Return type

Optional[bytes]

See also CreateModuleHeaderFromMagic().

Disassemble(out: Pro.Core.NTTextStream) → None

Disassembles the entire file.

Parameters

out (NTTextStream) – The output text stream.

See also DisassembleCode().

DisassembleCode(out: Pro.Core.NTTextStream, code_obj: Pkg.PYC.PyCode) → None

Disassembles a specific code object.

Parameters

• out (NTTextStream) – The output text stream.

• code_obj (PyCode) – The code object.

See also Disassemble().

GetEndOffset() → int

Returns

Returns the computed end offset of the PYC file.

Return type

int

GetModuleFileName() → Optional[str]

Returns

Returns the module file name if available; otherwise returns None.

Return type

Optional[str]

GetObjectMap() → Dict[int, Pkg.PYC.PyObject]

Returns

Returns the object tree as a map.

Return type

Dict[int, PyObject]

See also GetObjectTree().

GetObjectTree() → Pkg.PYC.PyObject

Returns

Returns the root object of the tree.

Return type

PyObject

See also GetObjectMap().

GetVersion() → Tuple[int, int]

Returns

Returns the Python major and minor version of the PYC file as a tuple.

Return type

Tuple[int, int]

See also CreateModuleHeaderFromVersion().

Parse(wo: Optional[Pro.Core.NTIWait] = None, verbose: bool = False) → bool

Parses the format.

Parameters

• wo (NTIWait) – An optional wait object for the parsing operation.

• verbose (bool) – If True, provides verbose output.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

class PyCComplex

Bases: Pkg.PYC.PyObject

This class represents a Python Binary Complex object (OBJECT_TYPE_BINARY_COMPLEX).

class PyCFloat

Bases: Pkg.PYC.PyObject

This class represents a Python Binary Float object (OBJECT_TYPE_BINARY_FLOAT).

class PyCode

Bases: Pkg.PYC.PyObject

This class represents a Python Code object (e.g., OBJECT_TYPE_CODE).

class PyComplex

Bases: Pkg.PYC.PyObject

This class represents a Python Complex object (OBJECT_TYPE_COMPLEX).

class PyDict

Bases: Pkg.PYC.PyObject

This class represents a Python Dictionary object (OBJECT_TYPE_DICT).

class PyEllipsis

Bases: Pkg.PYC.PyObject

This class represents a Python Ellipsis object (OBJECT_TYPE_ELLIPSIS).

class PyFalse

Bases: Pkg.PYC.PyObject

This class represents a Python False object (OBJECT_TYPE_FALSE).

class PyFloat

Bases: Pkg.PYC.PyObject

This class represents a Python Float object (OBJECT_TYPE_FLOAT).

class PyInt

Bases: Pkg.PYC.PyObject

This class represents a Python Integer object (e.g., OBJECT_TYPE_INT).

Methods:

ToInt()

Returns the integer value of the object.

ToInt() → int

Returns

Returns the integer value of the object.

Return type

int

class PyList

Bases: Pkg.PYC.PyObject

This class represents a Python List object (OBJECT_TYPE_LIST).

class PyLong

Bases: Pkg.PYC.PyObject

This class represents a Python Long object (e.g., OBJECT_TYPE_LONG).

Methods:

ToInt()

Returns the integer value of the object.

ToInt() → int

Returns

Returns the integer value of the object.

Return type

int

class PyNone

Bases: Pkg.PYC.PyObject

This class represents a Python None object (OBJECT_TYPE_NONE).

class PyNull

Bases: Pkg.PYC.PyObject

This class represents a Python Null object (OBJECT_TYPE_NULL).

class PyObject

This class represents the base class for every Python object.

Methods:

Dump(out[, inline])	Dumps the contents of the object to a text stream.
Equals(other)	Compares this Python object to another one.
GetChild(i)	Retrieves a child object.
GetChildCount()	Returns the number of child objects.
HasChildren()	Returns True if the object has children; otherwise returns False.

Attributes:

id	The object id (assigned by PYCObject).
is_ref	Variable that determines whether the object is a reference.
object_offset	The object offset.
object_size	The object size.
parent_id	The parent object id.
parent_pos	The parent position.
type	The object type (e.g., OBJECT_TYPE_NONE).

Dump(out: Pro.Core.NTTextStream, inline: bool = False) → None

Dumps the contents of the object to a text stream.

Parameters

• out (NTTextStream) – The text stream.

• inline (bool) – If True, dumps the contents on a single line.

Equals(other: Pkg.PYC.PyObject) → bool

Compares this Python object to another one.

Parameters

other (PyObject) – The other Python object.

Returns

Returns True if the objects are the same; otherwise returns False.

Return type

bool

GetChild(i: int) → Optional[Pkg.PYC.PyObject]

Retrieves a child object.

Parameters

i (int) – The index of the child object.

Returns

Returns the child object if successful; otherwise returns None.

Return type

Optional[PyObject]

See also GetChildCount().

GetChildCount() → int

Returns

Returns the number of child objects.

Return type

bool

See also GetChild().

HasChildren() → bool

Returns

Returns True if the object has children; otherwise returns False.

Return type

bool

See also GetChildCount().

id

The object id (assigned by PYCObject).

is_ref

Variable that determines whether the object is a reference.

object_offset

The object offset.

object_size

The object size.

parent_id

The parent object id.

parent_pos

The parent position.

type

The object type (e.g., OBJECT_TYPE_NONE).

class PySet

Bases: Pkg.PYC.PyObject

This class represents a Python Set object (OBJECT_TYPE_SET).

class PyStopIter

Bases: Pkg.PYC.PyObject

This class represents a Python StopIter object (OBJECT_TYPE_STOPITER).

class PyString

Bases: Pkg.PYC.PyObject

This class represents a Python String object (e.g., OBJECT_TYPE_STRING).

Methods:

ToString()

Returns the object as a string.

ToString() → str

Returns

Returns the object as a string.

Return type

str

class PyTrue

Bases: Pkg.PYC.PyObject

This class represents a Python True object (OBJECT_TYPE_TRUE).

class PyTuple

Bases: Pkg.PYC.PyObject

This class represents a Python Tuple object (e.g., OBJECT_TYPE_TUPLE).