feat: support Python class

[toaction]

In Python, a class is declared as follows：

class Person:

    def __init__(self, name, age):
        self.name = name
        self.age = age

    def greet(self):
        print(f"hello，my name is {self.name}, {self.age} years old.")

person1 = Person("Micro", 25)
person1.greet()

How to use llgo to extract class symbol information and convert it into structures and methods ?

[toaction]

Class components

In Python, a class consists of the following main elements:

1. Class name
2. Attributes: class attributes, instance attributes
3. Methods: class methods, instance methods, static methods
4. Special methods: constructors and destructors, string representations, operator overloading
5. Property decorators
6. Inheritance
7. Private and protected members
8. Documentation strings

Complete Example

class Animal:
    def __init__(self, name):
        self.name = name

class Dog(Animal):  # inherit
    
    # class attribute
    class_name = "Dog"

    def __init__(self, name, age):
        """
        Dog constructor
        """
        super().__init__(name)
        self._age = age      # instance attribute


    # instance method, the first parameter is represent the instance
    def speak(self):      # self is must
        return f"{self.name} says Woof!"
    
    # class method, must add @classmethod decorator, the first parameter represent the class
    @classmethod
    def get_class_name(cls):      # cls is must
        return cls.class_name

    # static method, does not need to pass any parameter
    @staticmethod
    def static_method(x, y):
        return x + y
    
    # special method
    def __str__(self):
        return f"{self.name} is {self._age} years old"
    
    # property
    @property
    def age(self):
        return self._age

Call

dog = Dog("Buddy", 5)   # create a dog instance, call __init__

Dog.class_name    # call class attribute

dog.speak()    # call instance method

Dog.get_class_name()    # call class method

Dog.static_method(1, 2)    # call static method

str(dog)    # call __str__ method

dog.age    # call property

Although static methods are called in the same way as class methods, they cannot directly access class or instance attributes and do not have self or cls parameters.

[toaction]

Symbol information in Class

dict attribute

• Class.__dict__: stores class attributes, methods, class methods, static methods, etc.
• Instance.__dict__: stores instance attributes, no methods.
• Unable to get the properties and methods of the parent class.

key and type from Dog.__dict__:

• class_name: str
• get_class_name: classmethod
• static_method: staticmethod
• age: property
• speak: function
• __module__: str
• __str__: function
• __doc__: NoneType
• __init__: function

symbol information

def inspect_dog():
    print(f"class name: {Dog.__name__}")
    print(f"module: {Dog.__module__}")
    print(f"direct parent class: {[base.__name__ for base in Dog.__bases__]}")
    class_dict = Dog.__dict__
    
    categories = {
        'class_attributes': [],
        'instance_methods': [],
        'class_methods': [],
        'static_methods': [],
        'properties': [],
        'special_methods': []
    }
    
    for key, value in class_dict.items():
        if key.startswith('__') and key.endswith('__'):
            categories['special_methods'].append(key)
        elif isinstance(value, classmethod):
            categories['class_methods'].append(key)
        elif isinstance(value, staticmethod):
            categories['static_methods'].append(key)
        elif isinstance(value, property):
            categories['properties'].append(key)
        elif callable(value):
            categories['instance_methods'].append(key)
        else:
            categories['class_attributes'].append((key, value, type(value).__name__))
    
    for category, items in categories.items():
        print(f"{category}: {items}")

Visibility

Convention over Enforcement

• Public: A normal identifier name, accessible from anywhere
• Protected: Begins with a single underscore and is used only within the class and its subclasses
• Private: Begins with a double underscore (__) and does not end with a double underscore; is not accessible externally

[toaction]

Python C API

create instance

Py_Initialize();

// import module
PyObject *module = PyImport_ImportModule("my_class");

// get class
PyObject *dog_class = PyObject_GetAttrString(module, "Dog");

// create instance
// dog = Dog("Buddy", 5)
PyObject *args = PyTuple_New(2);
PyTuple_SetItem(args, 0, PyUnicode_FromString("Buddy"));
PyTuple_SetItem(args, 1, PyLong_FromLong(5));
PyObject *dog_instance = PyObject_CallObject(dog_class, args);

instance methods, class methods, static methods, special methods

// dog.speak()
PyObject *result = PyObject_CallMethod(dog_instance, "speak", NULL);

// Dog.get_class_name()
PyObject *class_method_result = PyObject_CallMethod(dog_class, "get_class_name", NULL);

// Dog.static_method(1,2)
PyObject *static_result = PyObject_CallMethod(dog_class, "static_method",  "ii", 1, 2);

// str(dog)
PyObject *str_result = PyObject_CallMethod(dog_instance, "__str__", NULL);

class attributes, property

// Dog.class_name
PyObject *class_attr = PyObject_GetAttrString(dog_class, "class_name");

// set dog.age
PyObject *age_prop = PyObject_SetAttrString(dog_instance, "age", 11);

[toaction]

Class Declaration and Creation

Class declaration: Structure or py.Object

Create object: through the NewClassName method.

Structure

Declaration

/* Animal class */
type Animal py.Object

//llgo:link NewAnimal py.Animal
func NewAnimal(name string) *Animal {return nil}

//llgo:link (*Animal).Animal_method py.method.animal_method
func (a *Animal) Animal_method() *py.Object {return nil}

/* Dog class */
type Dog struct {
	Animal  // inherit    
}

Use

dog := NewDog("Buddy", 5)
dog.Animal_method()
dog.Speak()

Advantages

• Clear structure, same as Python usage
• Support inheritance and be able to call parent class methods

Difficulty

• The return type of cpython api is py.Object. How to convert it to the corresponding structure?
• Python supports class.attribute to access and set public attributes of classes or objects. Should these attributes be placed in a structure or converted to method calls?

py.Object

Set all class objects to py.Object type

/* Animal class */
type Animal py.Object

//llgo:link NewAnimal py.Animal
func NewAnimal(name string) *Animal { return nil }

func (a *Animal) Animal_method() *py.Object { return nil }

/* Dog class */
type Dog py.Object

//llgo:link NewDog py.Dog
func NewDog(name string, age int) *Dog { return nil }

//llgo:link (*Dog).Speak py.method.speak
func (d *Dog) Speak() *py.Object { return nil }

Advantages:

• No need to consider class-to-struct mapping

Disadvantages:

• No support for inheritance
• No support for direct reading and modification of properties

[toaction]

Method conversion

Python method calls

There are four types of methods declared in Python classes: instance methods, class methods, static methods, and special methods:

# instance method
def speak(self):
    return f"{self.name} says Woof!"

# class method
@classmethod
def get_class_name(cls):
    return cls.class_name

# static method
@staticmethod
def static_method(x, y):
    return x + y

# special method
def __str__(self):
    return f"{self.name} is {self._age} years old"

How to call

dog = Dog("Buddy", 5)
    
# instance method
dog.speak()
dog.get_class_name()
dog.static_method(1, 2)
str(dog)

# class method
Dog.get_class_name()
Dog.static_method(1, 2)

LLGo Bindings

Since Type.method() is not supported in Go, the simplest approach is to convert all methods into instance methods.

//llgo:link NewDog py.Dog
func NewDog(name string, age int) *Dog {return nil}

//llgo:link (*Dog).Speak py.Dog.speak
func (d *Dog) Speak() *py.Object {return nil}

//llgo:link (*Dog).Get_class_name py.Dog.get_class_name
func (d *Dog) Get_class_name() *py.Object {return nil}

//llgo:link (*Dog).Static_method py.Dog.static_method
func (d *Dog) Static_method(a int, b int) *py.Object {return nil}

//llgo:link (*Dog).Str py.Dog.__str__
func (d *Dog) Str() *py.Object {return nil}

For static methods, they can exist independently of classes and instances, so they can be converted into global functions.

//go:linkname Static_method py.Dog.static_method
func Static_method(a int, b int) *py.Object

But one problem with this approach is that the method mapped via the go:link directive is py.Class.static_method, not the regular py.function.

[toaction]

Attributes and Properties

Python declaration and call

declaration

class_name = "Dog"

def __init__(self, name, age):
    self.name = name
    self._age = age

@property
def age(self):
    return self._age + 10

@age.setter
def age(self, value):
    self._age = value

call

• cls.class_attribute
• obj.instance_attribute
• obj.property

dog = Dog("Buddy", 5)

print(dog.name)
dog.name = "Lucy"
print(dog.name)

LLGo Bindings

For Python C API, getting attributes and properties can only be done through PyObject_GetAttr.

1. Mapping attributes and properties to structure fields.

/* Dog class */
type Dog struct {
	Animal  // inherit 
	Class_name *py.Object
	Name *py.Object
	Age *py.Object   
}

Advantages:

• Visually displays all fields
• Convenient direct access, consistent with Python calling methods

Disadvantages:

• Difficult to map attribute names to field values
• Difficult to call cpython api
• Go allows for direct modification of field values, but Python properties without setter methods cannot be modified

2. Convert all to methods (whether they need to be mapped to setter and getter methods)，The llgo:link directive needs to be designed properly

//llgo:link (*Dog).Name py.getAttr.name
func (d *Dog) Name() *py.Object {return nil}

or

//llgo:link (*Dog).SetName py.setAttr.name
func (d *Dog) SetName(name *py.Object) c.Int {return 0}

//llgo:link (*Dog).GetName py.getAttr.name
func (d *Dog) GetName() *py.Object {return nil}

[toaction]

What kind of symbol information needs to be extracted ?

1. name: class name.
2. module_name: The module name, used to determine whether it is in the same module as the parent class.
3. bases: The inherited class name and the module where the parent class is located.
4. init_method: init method signature, use to generate newClass method.
5. attributes: name, Prepare for set and get methods.
6. properties: name, Prepare for set and get methods.
7. instance_methods: name and signature.
8. class_methods: name and signature.
9. static_methods: name and signature.
10. special_methods: name and signature.

name: Dog
module: dog
bases: [('Animal', 'animal')]
properties: ['age']
attributes: ['dog_name']
instance_methods: [('bark', '(self)'), ('say', '(self, msg)')]
class_methods: [('get_dog_name', None)]
static_methods: [('static_method', None)]
special_methods: [('__str__', '(self)')]
init_method: (self, name, age)

[toaction]

What should LLGo do to match LLGo Bindings?

create instance

Python

dog = Dog("Buddy", 5)

LLGo Binding

/* Dog class */
type Dog struct {
	Animal  // inherit  
}

//llgo:link NewDog py.Dog
func NewDog(name string, age int) *Dog {return nil}

LLGo

PyObject *module = PyImport_ImportModule("dog");
PyObject *dog_class = PyObject_GetAttrString(module, "Dog");
PyObject *args = PyTuple_New(2);
PyTuple_SetItem(args, 0, PyUnicode_FromString("Buddy"));
PyTuple_SetItem(args, 1, PyLong_FromLong(5));
PyObject *dog_instance = PyObject_CallObject(dog_class, args);

call methods

Python

dog.speak()

LLGo Binding

//llgo:link (*Dog).Speak py.method.speak
func (d *Dog) Speak() *py.Object {return nil}

LLGo need:

PyObject *result = PyObject_CallMethod(dog_instance, "speak", NULL);

get and set attributes or properties

Python

name = dog.name

LLGo Bindings

//llgo:link (*Dog).GetDogName py.attr.dog_name
func (d *Dog) GetDogName() *py.Object {return nil}

LLGo

PyObject *age_prop = PyObject_GetAttrString(dog_instance, "name");

[toaction]

Final Design

Class and Instance

Currently only single inheritance is supported.

type Animal struct {
	py.Object
}

//go:linkname NewAnimal py.Animal
func NewAnimal(name *py.Object) *Animal

type Dog struct {
	Animal
}

//go:linkname NewDog py.Dog
func NewDog(name *py.Object, age *py.Object) *Dog

Methods

//llgo:link (*Dog).Speak py.Dog.speak
func (d *Dog) Speak(msg py.Object) *py.Object {
	return nil
}

Properties

//llgo:link (*Dog).Age py.Dog.age.__get__
func (d *Dog) Age() *py.Object {
	return nil
}

//llgo:link (*Dog).SetAge py.Dog.age.__set__
func (d *Dog) SetAge(age *py.Object) { }

more details can see #21.