subprojects: Prepare for release

Black has changed how it lays out a call whose argument is a
multiline string, and a `with` statement holding several contexts.

examples/child_gating.py

@@ -42,7 +42,8 @@ class Application:
         print("✔ enable_child_gating()")
         session.enable_child_gating()
         print("✔ create_script()")
-        script = session.create_script("""\
+        script = session.create_script(
+            """\
 Interceptor.attach(Module.getGlobalExportByName('open'), {
   onEnter(args) {
     send({
@@ -51,7 +52,8 @@ Interceptor.attach(Module.getGlobalExportByName('open'), {
     });
   }
 });
-""")
+"""
+        )
         script.on("message", lambda message, data: self._reactor.schedule(lambda: self._on_message(pid, message)))
         print("✔ load()")
         script.load()

examples/rpc.py

@@ -1,7 +1,8 @@
 import frida
 
 session = frida.attach("Twitter")
-script = session.create_script("""\
+script = session.create_script(
+    """\
 rpc.exports = {
   hello: function () {
     return 'Hello';
@@ -10,7 +11,8 @@ rpc.exports = {
     oops;
   }
 };
-""")
+"""
+)
 script.load()
 api = script.exports_sync
 print("api.hello() =>", api.hello())

examples/session_persist_timeout.py

@@ -22,7 +22,8 @@ class Application:
         self._session = session
         session.on("detached", lambda *args: self._reactor.schedule(lambda: self._on_detached(*args)))
 
-        script = session.create_script("""
+        script = session.create_script(
+            """
 let _puts = null;
 
 Interceptor.attach(DebugSymbol.getFunctionByName('f'), {
@@ -47,7 +48,8 @@ function puts(s) {
   }
   _puts(Memory.allocUtf8String(s));
 }
-""")
+"""
+        )
         self._script = script
         script.on("message", lambda *args: self._reactor.schedule(lambda: self._on_message(*args)))
         script.load()

examples/spawn_gating.py

@@ -29,7 +29,8 @@ class Application:
         session = self._device.attach(pid)
         session.on("detached", lambda reason: self._reactor.schedule(lambda: self._on_detached(pid, session, reason)))
         print("✔ create_script()")
-        script = session.create_script("""\
+        script = session.create_script(
+            """\
 const puts = new NativeFunction(Module.getGlobalExportByName('puts'), 'int', ['pointer']);
 puts(Memory.allocUtf8String('Hello from Frida agent'));
 Interceptor.attach(Module.getGlobalExportByName('open'), {
@@ -40,7 +41,8 @@ Interceptor.attach(Module.getGlobalExportByName('open'), {
     });
   }
 });
-""")
+"""
+        )
         script.on("message", lambda message, data: self._reactor.schedule(lambda: self._on_message(pid, message)))
         print("✔ load()")
         script.load()

frida/frida_bindgen/assets/codegen_gobject_methods.c

@@ -910,6 +910,9 @@ propagate_error:
 static PyObject *
 PyGObject_marshal_variant (GVariant * variant)
 {
+  if (variant == NULL)
+    PyFrida_RETURN_NONE;
+
   switch (g_variant_classify (variant))
   {
     case G_VARIANT_CLASS_STRING:

frida/frida_bindgen/codegen.py

@@ -34,10 +34,14 @@ def read_asset(name: str) -> str:
     return (ASSETS_DIR / name).read_text(encoding="utf-8")
 
 
-FACADE_TYPING_IMPORTS = (
-    "from typing import (Any, Callable, Dict, List, Literal, Mapping, NotRequired, Optional, Tuple, TypedDict, "
-    "Sequence, Union, ParamSpec, TypeVar, cast, overload)"
-)
+FACADE_TYPING_IMPORTS = """\
+from typing import (Any, Callable, Dict, List, Literal, Mapping, Optional, Tuple, Sequence, Union, TypeVar, cast,
+                    overload)
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, ParamSpec, TypedDict
+else:
+    from typing_extensions import NotRequired, ParamSpec, TypedDict"""
 
 
 def generate_facade_preludes(model: Model) -> List[str]:
@@ -88,17 +92,25 @@ def _to_envp(value):
 
 def _make_options(cls, values, selectors):
     options = cls()
+    _apply_settings(options, values, selectors)
+    return options
+
+
+def _apply_settings(impl, values, selectors):
     for name, value in values.items():
         if value is None:
             continue
         select = selectors.get(name)
         if select is None:
-            setattr(options, name, value)
+            setattr(impl, name, _unwrap(value))
+        elif isinstance(value, dict):
+            add = getattr(impl, select)
+            for key, element in value.items():
+                add(key, _unwrap(element))
         else:
-            add = getattr(options, select)
+            add = getattr(impl, select)
             for element in value:
-                add(element)
-    return options
+                add(_unwrap(element))
 
 
 _current_cancellable = threading.local()
@@ -182,17 +194,25 @@ def _to_envp(value):
 
 def _make_options(cls, values, selectors):
     options = cls()
+    _apply_settings(options, values, selectors)
+    return options
+
+
+def _apply_settings(impl, values, selectors):
     for name, value in values.items():
         if value is None:
             continue
         select = selectors.get(name)
         if select is None:
-            setattr(options, name, value)
+            setattr(impl, name, _unwrap(value))
+        elif isinstance(value, dict):
+            add = getattr(impl, select)
+            for key, element in value.items():
+                add(key, _unwrap(element))
         else:
-            add = getattr(options, select)
+            add = getattr(impl, select)
             for element in value:
-                add(element)
-    return options
+                add(_unwrap(element))
 
 
 _current_cancellable: contextvars.ContextVar = contextvars.ContextVar("frida_current_cancellable", default=None)
@@ -416,7 +436,7 @@ def generate_aio_async_method(method: Method, model: Model) -> Optional[str]:
     if method.return_value is not None:
         call = wrap_result(call, method.return_value.type, model)
 
-    ret = "None" if method.return_value is None else pyi_type(method.return_value.type, model)
+    ret = facade_return_type(method, model)
 
     return f"""    async def {method.name}({signature}) -> {ret}:
         return {call}"""
@@ -440,7 +460,7 @@ def generate_custom_facade_method(
     body = textwrap.indent(logic.strip(), " " * 8)
     keyword = "async def" if awaitable else "def"
 
-    ret = "None" if method.return_value is None else pyi_type(method.return_value.type, model)
+    ret = facade_return_type(method, model)
 
     return f"""    {keyword} {method.name}({signature}) -> {ret}:
 {body}
@@ -516,10 +536,8 @@ def generate_facade_init(otype: ObjectType) -> str:
 {body}"""
 
     return f"""    def __init__(self, *args, **kwargs):
-        self._impl = _frida.{otype.py_name}(
-            *[_unwrap(a) for a in args],
-            **{{k: _unwrap(v) for k, v in kwargs.items()}},
-        )
+        self._impl = _frida.{otype.py_name}(*[_unwrap(a) for a in args])
+        _apply_settings(self._impl, kwargs, {build_option_selectors(otype)})
         setup = getattr(self, "_setup", None)
         if setup is not None:
             setup()"""
@@ -643,13 +661,13 @@ def generate_py_sync_method(method: Method, model: Model) -> Optional[str]:
         return None
 
     params = [facade_param(param, model) for param in method.input_parameters]
-    names = ", ".join(param.name for param in method.input_parameters)
+    names = ", ".join(facade_argument(param, model) for param in method.input_parameters)
 
     call = f"self._impl.{method.name}({names})"
     if method.return_value is not None:
         call = wrap_result(call, method.return_value.type, model)
 
-    ret = "None" if method.return_value is None else pyi_type(method.return_value.type, model)
+    ret = facade_return_type(method, model)
 
     return f"""    def {method.name}({facade_signature(method, params)}) -> {ret}:
         return {call}"""
@@ -659,6 +677,12 @@ def facade_signature(method: Method, params: List[str]) -> str:
     return ", ".join(["self"] + (method.custom_facade_params or params))
 
 
+def facade_argument(param, model: Model) -> str:
+    if resolve_input_object_type(param.type, model) is not None:
+        return f"_unwrap({param.name})"
+    return param.name
+
+
 def facade_param(param, model: Model) -> str:
     annotation = pyi_type(param.type, model)
     if param.nullable:
@@ -679,7 +703,7 @@ def generate_py_async_method(method: Method, model: Model) -> Optional[str]:
     if method.return_value is not None:
         call = wrap_result(call, method.return_value.type, model)
 
-    ret = "None" if method.return_value is None else pyi_type(method.return_value.type, model)
+    ret = facade_return_type(method, model)
 
     return f"""    def {method.name}({signature}) -> {ret}:
         return {call}"""
@@ -769,13 +793,22 @@ def generate_pyi_class(otype: ObjectType, model: Model) -> List[str]:
 
     body = []
 
-    ctor = next(iter(otype.constructors), None)
-    if ctor is not None and not ctor.throws:
-        params = pyi_parameters(ctor.input_parameters, model)
+    primary = inline_constructor(otype)
+    if primary is not None:
+        params = pyi_parameters(primary.input_parameters, model)
         if params is not None:
             signature = ", ".join(["self"] + params)
             body.append(f"    def __init__({signature}) -> None: ...")
 
+    for ctor in otype.constructors:
+        if ctor is primary:
+            continue
+        params = pyi_parameters(ctor.input_parameters, model)
+        if params is None:
+            continue
+        body.append("    @staticmethod")
+        body.append(f"    def {ctor.name}({', '.join(params)}) -> {otype.py_name}: ...")
+
     if otype.name == "Object":
         body.append("    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...")
         body.append("    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...")
@@ -836,7 +869,13 @@ def pyi_method(method: Method, model: Model) -> Optional[str]:
     if params is None:
         return None
     signature = ", ".join(["self"] + params)
-    ret = "None" if method.return_value is None else pyi_type(method.return_value.type, model)
+    out = method.optional_out_parameter
+    if out is not None:
+        ret = f"Optional[{pyi_type(out.type, model)}]"
+    elif method.return_value is None:
+        ret = "None"
+    else:
+        ret = pyi_type(method.return_value.type, model)
     return f"    def {method.name}({signature}) -> {ret}: ..."
 
 
@@ -924,6 +963,8 @@ def generate_extension_c(model: Model) -> str:
             code += generate_interface_implementation(otype)
 
         code += generate_object_type_constructor(otype)
+        for ctor in factory_constructors(otype):
+            code += generate_factory_function(otype, ctor, build_constructor_marshals(ctor))
 
     return code
 
@@ -1198,6 +1239,10 @@ def generate_prototypes(model: Model) -> str:
                 "",
                 f"static int {otype_cprefix}_init ({otype_cprefix} * self, PyObject * args, PyObject * kw);",
             ]
+            for ctor in factory_constructors(otype):
+                prototypes.append(
+                    f"static PyObject * {otype_cprefix}_{ctor.name} (PyObject * self, PyObject * args, PyObject * kw);"
+                )
             if implementable_interface(otype):
                 prototypes += [
                     f"static int {otype_cprefix}_traverse (PyObject * self, visitproc visit, void * arg);",
@@ -1258,13 +1303,15 @@ def generate_object_type_toplevel_definitions(model: Model) -> str:
         cprefix = otype.c_symbol_prefix
 
         if otype.name == "Object":
-            defs.append(f"""PYFRIDA_DEFINE_BASETYPE ("_frida.{otype.py_name}", {otype.py_name}, g_object_unref,
+            defs.append(
+                f"""PYFRIDA_DEFINE_BASETYPE ("_frida.{otype.py_name}", {otype.py_name}, g_object_unref,
   {{ Py_tp_doc, "{otype.name}" }},
   {{ Py_tp_init, {cprefix}_init }},
   {{ Py_tp_dealloc, {cprefix}_dealloc }},
   {{ Py_tp_methods, {cprefix}_methods }},
   {{ Py_tp_getset, {cprefix}_getsets }},
-);""")
+);"""
+            )
             continue
 
         parent = otype.parent
@@ -1284,12 +1331,14 @@ def generate_object_type_toplevel_definitions(model: Model) -> str:
             )
             continue
 
-        defs.append(f"""PYFRIDA_DEFINE_TYPE ("_frida.{otype.py_name}", {otype.py_name}, {parent_name}, g_object_unref,
+        defs.append(
+            f"""PYFRIDA_DEFINE_TYPE ("_frida.{otype.py_name}", {otype.py_name}, {parent_name}, g_object_unref,
   {{ Py_tp_doc, "{otype.name}" }},
   {{ Py_tp_init, {cprefix}_init }},
   {{ Py_tp_methods, {cprefix}_methods }},
   {{ Py_tp_getset, {cprefix}_getsets }},
-);""")
+);"""
+        )
 
     return "\n\n".join(defs)
 
@@ -1314,6 +1363,9 @@ def generate_object_type_methods(otype: ObjectType) -> str:
         functions.append(function)
         entries.append(entry)
 
+    for ctor in factory_constructors(otype):
+        entries.append(factory_method_entry(otype, ctor))
+
     return f"""{"".join(functions)}
 static PyMethodDef {otype.c_symbol_prefix}_methods[] =
 {{
@@ -1329,6 +1381,11 @@ def generate_method(otype: ObjectType, method: Method) -> Optional[Tuple[str, st
     marshal = synchronous_method_return_marshal(method)
     if marshal is None:
         return None
+    out = method.optional_out_parameter
+    if out is not None:
+        marshal = build_return_marshal(out.type, method.object_type.model)
+        if marshal is None:
+            return None
     params = []
     for param in method.input_parameters:
         sync_param = build_sync_param(param)
@@ -1672,14 +1729,17 @@ def generate_synchronous_method(otype: ObjectType, method: Method, marshal: str,
     indent = " " * (len(otype.c_symbol_prefix) + len(method.name) + 3)
     handle = f"({otype.c_type} *) PY_GOBJECT_HANDLE (self)"
     returns_strv = method.return_value is not None and method.return_value.type.name == "utf8[]"
+    out = method.optional_out_parameter
     call_arg_list = [handle] + [p.call_arg for p in params]
     if returns_strv:
         call_arg_list.append("&retval_length")
+    if out is not None:
+        call_arg_list.append(f"&{out.name}")
     if method.throws:
         call_arg_list.append("&error")
     call = f"{method.c_identifier} ({', '.join(call_arg_list)})"
 
-    if not params and not method.throws and not returns_strv:
+    if not params and not method.throws and not returns_strv and out is None:
         if method.return_value is None:
             body = f"  {call};\n\n  PyFrida_RETURN_NONE;"
         else:
@@ -1698,6 +1758,8 @@ static PyObject *
         decls.append("  GError * error = NULL;")
     if returns_strv:
         decls.append("  gint retval_length;")
+    if out is not None:
+        decls.append(f"  {out_parameter_storage_type(out)} {out.name};")
     for p in params:
         decls += [f"  {line}" for line in p.decl.splitlines()]
 
@@ -1712,7 +1774,15 @@ static PyObject *
 
     pre = "".join(f"\n  {p.pre}\n" for p in params if p.pre)
 
-    if method.return_value is None:
+    if out is not None:
+        invocation = f"  gboolean found = {call};"
+        success = (
+            "  if (found)\n"
+            f"    result = {marshal.format(value=out.name)};\n"
+            "  else\n"
+            "  {\n    Py_IncRef (Py_None);\n    result = Py_None;\n  }"
+        )
+    elif method.return_value is None:
         invocation = f"  {call};"
         success = "  Py_IncRef (Py_None);\n  result = Py_None;"
     elif returns_strv:
@@ -1757,6 +1827,22 @@ static PyObject *
 """
 
 
+def facade_return_type(method: Method, model: Model) -> str:
+    out = method.optional_out_parameter
+    if out is not None:
+        return f"Optional[{pyi_type(out.type, model)}]"
+    if method.return_value is None:
+        return "None"
+    return pyi_type(method.return_value.type, model)
+
+
+def out_parameter_storage_type(param: Parameter) -> str:
+    """What the caller declares: the out parameter's own type, less the pointer."""
+    c = param.type.c
+    assert c.endswith("*"), c
+    return c[:-1].strip()
+
+
 def synchronous_method_return_marshal(method: Method) -> Optional[str]:
     if method.is_async or method.is_property_accessor:
         return None
@@ -1839,6 +1925,16 @@ def build_sync_param(param: Parameter) -> Optional["SyncParam"]:
             cleanup=f"g_clear_pointer (&{name}, g_variant_unref);",
         )
 
+    if resolve_input_object_type(param.type, param.object_type.model) is not None:
+        return SyncParam(
+            decl=f"PyObject * {name}_obj;\n{param.type.c} {name} = NULL;",
+            fmt="O",
+            parse_args=[f"&{name}_obj"],
+            pre=f"""if ({name}_obj != Py_None)
+    {name} = ({param.type.c}) PY_GOBJECT_HANDLE ({name}_obj);""",
+            call_arg=name,
+        )
+
     return None
 
 
@@ -2255,28 +2351,55 @@ def generate_object_type_constructor(otype: ObjectType) -> str:
     if implementable_interface(otype):
         return generate_interface_init(otype)
 
-    ctor = next(iter(otype.constructors), None)
+    ctor = primary_constructor(otype)
 
     if ctor is None:
         return generate_bare_init(otype)
 
-    marshals: Optional[List[ParamMarshal]] = None
-    if not ctor.throws:
-        marshals = []
-        for param in ctor.input_parameters:
-            marshal = build_param_marshal(param)
-            if marshal is None:
-                marshals = None
-                break
-            marshal.optional = param.optional
-            marshals.append(marshal)
+    if ctor.throws:
+        return generate_unconstructable_init(otype)
 
+    marshals = build_constructor_marshals(ctor)
     if marshals is None:
         return generate_unconstructable_init(otype)
 
     return generate_constructor_init(otype, ctor, marshals)
 
 
+def primary_constructor(otype: ObjectType) -> Optional[Procedure]:
+    if not otype.constructors:
+        return None
+    return next((c for c in otype.constructors if c.name == "new"), otype.constructors[0])
+
+
+def inline_constructor(otype: ObjectType) -> Optional[Procedure]:
+    """The constructor __init__ takes; one that throws is reached as a factory instead."""
+    ctor = primary_constructor(otype)
+    if ctor is None or ctor.throws:
+        return None
+    return ctor
+
+
+def factory_constructors(otype: ObjectType) -> List[Procedure]:
+    primary = inline_constructor(otype)
+    return [
+        ctor
+        for ctor in otype.constructors
+        if ctor is not primary and not ctor.is_async and build_constructor_marshals(ctor) is not None
+    ]
+
+
+def build_constructor_marshals(ctor: Procedure) -> Optional[List["ParamMarshal"]]:
+    marshals = []
+    for param in ctor.input_parameters:
+        marshal = build_param_marshal(param)
+        if marshal is None:
+            return None
+        marshal.optional = param.optional
+        marshals.append(marshal)
+    return marshals
+
+
 def generate_interface_init(otype: ObjectType) -> str:
     n = interface_impl_names(otype)
     indent = constructor_indent(otype)
@@ -2377,7 +2500,88 @@ static int
 {generate_constructor_tail(marshals)}"""
 
 
-def generate_argument_parse(marshals: List["ParamMarshal"]) -> str:
+def factory_method_entry(otype: ObjectType, ctor: Procedure) -> str:
+    return (
+        f'  {{ "{ctor.name}", (PyCFunction) {otype.c_symbol_prefix}_{ctor.name}, '
+        "METH_VARARGS | METH_KEYWORDS | METH_STATIC, NULL },"
+    )
+
+
+def generate_factory_function(otype: ObjectType, ctor: Procedure, marshals: List["ParamMarshal"]) -> str:
+    indent = " " * (len(otype.c_symbol_prefix) + len(ctor.name) + 3)
+
+    decls = [line for m in marshals for line in m.decls]
+    decls.append(f"{otype.c_type} * handle;")
+    if ctor.throws:
+        decls.append("GError * error = NULL;")
+    decls.append("PyObject * result = NULL;")
+    decls_block = indent_c_code("\n".join(decls), 1, prologue="\n")
+
+    keyword_decl = ""
+    parse_block = ""
+    if marshals:
+        keywords = ", ".join([f'"{m.keyword}"' for m in marshals] + ["NULL"])
+        keyword_decl = f"\n  static char * keywords[] = {{ {keywords} }};"
+        parse_block = "\n" + generate_argument_parse(marshals, on_failure="return NULL;")
+
+    post_block = ""
+    for m in marshals:
+        if m.post is not None:
+            post_block += indent_c_code(m.post, 1, prologue="\n") + "\n"
+
+    call_args = [m.call_arg for m in marshals]
+    if ctor.throws:
+        call_args.append("&error")
+    call = f"handle = ({otype.c_type} *) {ctor.c_identifier} ({', '.join(call_args)});"
+
+    error_block = ""
+    if ctor.throws:
+        error_block = """
+  if (error != NULL)
+  {
+    result = PyFrida_raise (error);
+    goto beach;
+  }
+"""
+
+    take_handle = f"result = PyGObject_new_take_handle (g_steal_pointer (&handle), PYFRIDA_TYPE ({otype.py_name}));"
+
+    return f"""
+static PyObject *
+{otype.c_symbol_prefix}_{ctor.name} (PyObject * self,
+{indent}PyObject * args,
+{indent}PyObject * kw)
+{{{keyword_decl}{decls_block}
+{parse_block}{post_block}
+  {call}
+{error_block}
+  {take_handle}
+
+{generate_factory_tail(marshals, ctor.throws)}"""
+
+
+def generate_factory_tail(marshals: List["ParamMarshal"], throws: bool) -> str:
+    cleanups = [m.cleanup for m in marshals if m.cleanup is not None]
+    cleanup_block = indent_c_code("\n".join(reversed(cleanups)), 1) if cleanups else ""
+
+    if throws or constructor_needs_beach(marshals):
+        prologue = f"{cleanup_block}\n\n" if cleanup_block else ""
+        return f"""beach:
+{prologue}  return result;
+}}
+"""
+    if cleanup_block:
+        return f"""{cleanup_block}
+
+  return result;
+}}
+"""
+    return """  return result;
+}
+"""
+
+
+def generate_argument_parse(marshals: List["ParamMarshal"], on_failure: str = "return -1;") -> str:
     fmt = ""
     optional_started = False
     for m in marshals:
@@ -2391,7 +2595,7 @@ def generate_argument_parse(marshals: List["ParamMarshal"]) -> str:
     indent = " " * len("  if (!PyArg_ParseTupleAndKeywords (")
     parse_args_str = (",\n" + indent).join(parse_args)
     return f"""  if (!PyArg_ParseTupleAndKeywords ({parse_args_str}))
-    return -1;
+    {on_failure}
 """
 
 
@@ -2564,10 +2768,12 @@ def generate_object_type_structs(model: Model) -> str:
     for otype in model.regular_object_types:
         if otype.name == "Object":
             continue
-        structs.append(f"""struct _{otype.c_symbol_prefix}
+        structs.append(
+            f"""struct _{otype.c_symbol_prefix}
 {{
   {otype.parent_c_symbol_prefix} parent;
-}};""")
+}};"""
+        )
 
     return "\n\n".join(structs)
 

frida/frida_bindgen/model.py

@@ -17,6 +17,10 @@ class Model(core.Model):
 
 
 class ObjectType(core.ObjectType):
+    @cached_property
+    def methods(self) -> List["Method"]:
+        return [m for m in super().methods if not m.out_parameters or m.optional_out_parameter is not None]
+
     @cached_property
     def py_name(self) -> str:
         custom = self.customizations
@@ -144,6 +148,7 @@ class Method(core.Method):
         custom = self.customizations
         return custom.custom_logic if custom is not None else None
 
+
 class Property(core.Property):
     pass
 
@@ -276,6 +281,7 @@ def _make_class(
     type_struct,
     parent,
     constructors,
+    functions,
     methods,
     properties,
     signals,
@@ -290,6 +296,7 @@ def _make_class(
         type_struct,
         parent,
         constructors,
+        functions,
         methods,
         properties,
         signals,
@@ -306,6 +313,7 @@ def _make_interface(
     type_struct,
     parent,
     constructors,
+    functions,
     methods,
     properties,
     signals,
@@ -319,6 +327,7 @@ def _make_interface(
         type_struct,
         parent,
         constructors,
+        functions,
         methods,
         properties,
         signals,

subprojects/frida-core.wrap

@@ -1,6 +1,6 @@
 [wrap-git]
 url = https://github.com/frida/frida-core.git
-revision = 17.17.0
+revision = 17.20.0
 depth = 1
 
 [provide]