From a0b1e6cafb4ee01ea6c448f85b4751ee2ee37a3e Mon Sep 17 00:00:00 2001 From: blueloveTH Date: Sun, 23 Apr 2023 14:06:32 +0800 Subject: [PATCH] ... --- docs/coding_style_guide.md | 4 +-- docs/features/basic.md | 2 +- docs/features/goto.md | 2 +- docs/features/ternary.md | 2 +- docs/license.md | 2 +- docs/modules/json.md | 4 +-- docs/modules/sys.md | 2 +- docs/performance.md | 2 +- docs/quick-start/02_interop.md | 7 +++--- docs/quick-start/03_attr.md | 46 +++++++++++++++++++++++++++++++--- docs/quick-start/04_call.md | 4 ++- plugins/flutter/README.md | 2 +- src/expr.h | 2 +- 13 files changed, 61 insertions(+), 20 deletions(-) diff --git a/docs/coding_style_guide.md b/docs/coding_style_guide.md index 02245d89..717e8012 100644 --- a/docs/coding_style_guide.md +++ b/docs/coding_style_guide.md @@ -30,7 +30,7 @@ int TestFunc(int x) { return x+1; } int testFunc(int x) { return x+1; } ``` -For special Python objects, use the same name as in Python. +For special python objects, use the same name as in python. ```cpp auto x = vm->None; @@ -55,7 +55,7 @@ For macros, use **SNAKE_CASE** ## Access control -Please use Python style access control. +Please use python style access control. We do not recommend to use C++ keywords such as `private` or `public` to achieve access control. Also do not write any trivial setter/getter. diff --git a/docs/features/basic.md b/docs/features/basic.md index b2dd6617..376c552c 100644 --- a/docs/features/basic.md +++ b/docs/features/basic.md @@ -5,7 +5,7 @@ order: 100 # basic -The following table shows the basic features of PocketPy with respect to [CPython](https://github.com/python/cpython). +The following table shows the basic features of pkpy with respect to [cpython](https://github.com/python/cpython). The features marked with `YES` are supported, and the features marked with `NO` are not supported. | Name | Example | Supported | diff --git a/docs/features/goto.md b/docs/features/goto.md index d1bf758e..1f338691 100644 --- a/docs/features/goto.md +++ b/docs/features/goto.md @@ -4,7 +4,7 @@ icon: dot # goto/label -PocketPy supports `goto` and `label` just like C. You are allowed to change the control flow unconditionally. +pkpy supports `goto` and `label` just like C. You are allowed to change the control flow unconditionally. ## Syntax diff --git a/docs/features/ternary.md b/docs/features/ternary.md index 0dfe9a72..1b4f0690 100644 --- a/docs/features/ternary.md +++ b/docs/features/ternary.md @@ -5,7 +5,7 @@ icon: dot # ternary op Ternary operator is a short hand `if...else`. -PocketPy supports both C and Python style ternary. +pkpy supports both c and python style ternary. ## Syntax diff --git a/docs/license.md b/docs/license.md index 059d2185..a25a58c1 100644 --- a/docs/license.md +++ b/docs/license.md @@ -6,7 +6,7 @@ label: License # License -PocketPy is licensed under the [MIT License](http://opensource.org/licenses/MIT). +pkpy is licensed under the [MIT License](http://opensource.org/licenses/MIT). ``` MIT License diff --git a/docs/modules/json.md b/docs/modules/json.md index d1860e5d..55bb0515 100644 --- a/docs/modules/json.md +++ b/docs/modules/json.md @@ -5,13 +5,13 @@ label: json ### `json.loads(s)` -Decode a JSON string into a PocketPy object. +Decode a JSON string into a python object. It is supported by the `eval()` function. ### `json.dumps(obj)` -Encode a PocketPy object into a JSON string. +Encode a python object into a JSON string. It is supported by the compiler with `JSON_MODE` enabled. diff --git a/docs/modules/sys.md b/docs/modules/sys.md index 6298b7c4..dbfa37ce 100644 --- a/docs/modules/sys.md +++ b/docs/modules/sys.md @@ -5,5 +5,5 @@ label: sys ### `sys.version` -The version of PocketPy. +The version of pkpy. diff --git a/docs/performance.md b/docs/performance.md index 5080da0b..cf682e86 100644 --- a/docs/performance.md +++ b/docs/performance.md @@ -6,7 +6,7 @@ label: Performance # Performance -Currently, PocketPy is almost~ fast as CPython 3.8. Here is a benchmark result of a special commit. +Currently, pkpy is almost~ fast as cpython 3.8. Here is a benchmark result of a special commit. Benchmark files are located in `benchmarks/`. diff --git a/docs/quick-start/02_interop.md b/docs/quick-start/02_interop.md index 57cc6731..1eb20415 100644 --- a/docs/quick-start/02_interop.md +++ b/docs/quick-start/02_interop.md @@ -4,7 +4,8 @@ label: 'Interop with PyObject' order: 90 --- -Any python object is represented by a `PyObject*`. +In pkpy, any python object is represented by a `PyObject*`. +There are 3 macros for you to do convert. + `VAR(...)`, create a `PyObject*` from a C type @@ -23,9 +24,9 @@ std::cout << CAST(Str, i); // abc #### Types -| `PyObject` type | C type | note | +| python type | C type | note | | ------------ | ---------------- | ---------------------- | -| `int` | `i64` | 62 bits integer | +| `int` | `i64` | 62 bits integer | | `float` | `f64` | 62 bits floating point | | `str` | `pkpy::Str` | | | `bool` | `bool` | | diff --git a/docs/quick-start/03_attr.md b/docs/quick-start/03_attr.md index 583812d0..3a4640c6 100644 --- a/docs/quick-start/03_attr.md +++ b/docs/quick-start/03_attr.md @@ -4,9 +4,47 @@ label: 'Attribute access' order: 80 --- -#### `PyObject* getattr(PyObject* obj, StrName name, bool throw_err=true)` +### Direct access -This method is equivalent to `getattr` in Python. +Some python objects have an instance dict, a.k.a, `__dict__` in cpython. +You can use `PyObject::attr()` to manipulate the instance dict of an object. + +```cpp +// get the `builtin` module +PyObject* builtins = vm->builtins; +// get `dict` type +PyObject* dict = builtins->attr("dict"); +// set `pi = 3.14` +builtins->attr().set("pi", VAR(3.14)); +``` + +However, you cannot call `attr` on an object which does not have an instance dict. +For example, the `int` object. + +```cpp +// create a `int` object +PyObject* obj = VAR(1); +// THIS IS WRONG!! WILL LEAD TO A SEGFAULT!! +PyObject* add = obj->attr("__add__"); +``` + +To determine whether an object has instance dict or not, you can use this snippet. + +```cpp +// 1. call `is_tagged` to check the object supports `->` operator +// 2. call `is_attr_valid` to check the existence of instance dict +PyObject* obj = VAR(1); +bool ok = !is_tagged(obj) && obj->is_attr_valid(); // false +``` + +### General access + +As you can see, direct access does not take care of derived attributes or methods. In most cases, what you need is `getattr` and `setattr`. +These two methods handle all possible cases. + +#### `PyObject* VM::getattr(PyObject* obj, StrName name, bool throw_err=true)` + +This method is equivalent to `getattr` in python. If the attribute is not found, it will return `nullptr` or throw an `AttributeError` depending on the value of `throw_err`. @@ -25,7 +63,7 @@ int result = CAST(int, ret); std::cout << result << std::endl; // 3 ``` -#### `void setattr(PyObject*, StrName, PyObject*)` +#### `void VM::setattr(PyObject*, StrName, PyObject*)` -This method is equivalent to `setattr` in Python. +This method is equivalent to `setattr` in python. It raises `TypeError` if the object does not support attribute assignment. \ No newline at end of file diff --git a/docs/quick-start/04_call.md b/docs/quick-start/04_call.md index 1cfe9417..b45c429e 100644 --- a/docs/quick-start/04_call.md +++ b/docs/quick-start/04_call.md @@ -4,7 +4,9 @@ label: 'Call a Python function' order: 70 --- -Use these to call a python function. +pkpy uses a variant of the [Vectorcall](https://peps.python.org/pep-0590/) protocol (PEP 590). + +There are 2 methods for calling a python function. + `PyObject* VM::call(PyObject* obj, ...)` + `PyObject* VM::call_method(PyObject* obj, StrName name, ...)` diff --git a/plugins/flutter/README.md b/plugins/flutter/README.md index 99fe2150..e60f2016 100644 --- a/plugins/flutter/README.md +++ b/plugins/flutter/README.md @@ -205,7 +205,7 @@ class _MyAppState extends State { # basic -The following table shows the basic features of PocketPy with respect to [CPython](https://github.com/python/cpython). +The following table shows the basic features of pkpy with respect to [cpython](https://github.com/python/cpython). The features marked with `YES` are supported, and the features marked with `NO` are not supported. | Name | Example | Supported | diff --git a/src/expr.h b/src/expr.h index 759a6a89..fcc01f58 100644 --- a/src/expr.h +++ b/src/expr.h @@ -429,7 +429,7 @@ struct TupleExpr: SequenceExpr{ }else{ // starred assignment target must be in a tuple if(items.size() == 1) return false; - // starred assignment target must be the last one (differ from CPython) + // starred assignment target must be the last one (differ from cpython) if(starred_i != items.size()-1) return false; // a,*b = [1,2,3] // stack is [1,2,3] -> [1,[2,3]]