[Bf-blender-cvs] [be5afe99875] master: PyAPI Docs: Add default values for bmesh API
Michal Srb
noreply at git.blender.org
Wed Dec 7 22:49:55 CET 2022
Commit: be5afe99875a17d5907770e8a1269534affa3b8b
Author: Michal Srb
Date: Wed Dec 7 14:57:15 2022 -0600
Branches: master
https://developer.blender.org/rBbe5afe99875a17d5907770e8a1269534affa3b8b
PyAPI Docs: Add default values for bmesh API
This diff improves the docs for bmesh by adding the default values to all methods. This is motivated by this issue https://github.com/nutti/fake-bpy-module/issues/118 in fake-bpy-module which generates a typed API for authoring Blender scripts and addons from the docs.
After this diff gets merged, the Blender docs get updated, and `fake-bpy-module` gets regenerated, the type signatures in `fake-bpy-module` will match the reality of Blender's API.
Here's a diff for the docs using the modified script:
https://gist.github.com/xixixao/1c83153adbcefbe0859f9cc9ba757d46
I "hardcoded" the defaults based on the types of the arguments, after some testing and consulting the Blender .c source for these APIs.
Here's a test script that verifies that the arguments with defaults added in this diff are indeed not required by Blender 3.3: https://gist.github.com/xixixao/adc4e5a076e80a63735bd60c7c9e7a0d
I made the minimum changes required to get this doc generation script fixed, but let me know if I should restructure this script more.
I also amended the comments of three args, 2 to align them with Python (NULL -> None) and one to mark it as optional (CurveProfile).
Reviewed By: Blendify
Differential Revision: https://developer.blender.org/D16400
===================================================================
M doc/python_api/rst_from_bmesh_opdefines.py
M source/blender/bmesh/intern/bmesh_opdefines.c
===================================================================
diff --git a/doc/python_api/rst_from_bmesh_opdefines.py b/doc/python_api/rst_from_bmesh_opdefines.py
index 0614538964d..c7b640227c8 100644
--- a/doc/python_api/rst_from_bmesh_opdefines.py
+++ b/doc/python_api/rst_from_bmesh_opdefines.py
@@ -234,28 +234,7 @@ def main():
args_in_index[:] = [i for (i, a) in enumerate(args_in) if type(a) == tuple]
if args_out is not None:
args_out_index[:] = [i for (i, a) in enumerate(args_out) if type(a) == tuple]
-
- fw(".. function:: %s(bm, %s)\n\n" % (b[0], ", ".join([args_in[i][0] for i in args_in_index])))
-
- # -- wash the comment
- comment_washed = []
- comment = [] if comment is None else comment
- for i, l in enumerate(comment):
- assert ((l.strip() == "") or
- (l in {"/*", " *"}) or
- (l.startswith(("/* ", " * "))))
-
- l = l[3:]
- if i == 0 and not l.strip():
- continue
- if l.strip():
- l = " " + l
- comment_washed.append(l)
-
- fw("\n".join(comment_washed))
- fw("\n")
- # -- done
-
+
# get the args
def get_args_wash(args, args_index, is_ret):
args_wash = []
@@ -296,26 +275,36 @@ def main():
if comment_next:
comment += ("\n" if comment_prev else "") + comment_next.strip()
+ default_value = None
if tp == BMO_OP_SLOT_FLT:
tp_str = "float"
+ default_value = '0'
+
elif tp == BMO_OP_SLOT_INT:
if tp_sub == BMO_OP_SLOT_SUBTYPE_INT_ENUM:
- tp_str = "enum in " + enums + ", default " + enums.split(",", 1)[0].strip("[")
+ default_value = enums.split(",", 1)[0].strip("[")
+ tp_str = "enum in " + enums + ", default " + default_value
elif tp_sub == BMO_OP_SLOT_SUBTYPE_INT_FLAG:
- tp_str = "set of flags from " + enums + ", default {}"
+ default_value = 'set()'
+ tp_str = "set of flags from " + enums + ", default " + default_value
else:
tp_str = "int"
+ default_value = '0'
elif tp == BMO_OP_SLOT_BOOL:
tp_str = "bool"
+ default_value = 'False'
elif tp == BMO_OP_SLOT_MAT:
tp_str = ":class:`mathutils.Matrix`"
+ default_value = 'mathutils.Matrix.Identity(4)'
elif tp == BMO_OP_SLOT_VEC:
tp_str = ":class:`mathutils.Vector`"
+ default_value = 'mathutils.Vector()'
if not is_ret:
tp_str += " or any sequence of 3 floats"
elif tp == BMO_OP_SLOT_PTR:
- tp_str = "dict"
assert tp_sub is not None
+ if 'if None' in comment:
+ default_value = 'None'
if tp_sub == BMO_OP_SLOT_SUBTYPE_PTR_BMESH:
tp_str = ":class:`bmesh.types.BMesh`"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_PTR_SCENE:
@@ -348,13 +337,16 @@ def main():
tp_str = "/".join(ls)
else:
tp_str = ("list of (%s)" % ", ".join(ls))
+ default_value = '[]'
del ls
elif tp == BMO_OP_SLOT_MAPPING:
if tp_sub & BMO_OP_SLOT_SUBTYPE_MAP_EMPTY:
tp_str = "set of vert/edge/face type"
+ default_value = 'set()'
else:
tp_str = "dict mapping vert/edge/face types to "
+ default_value = '{}'
if tp_sub == BMO_OP_SLOT_SUBTYPE_MAP_BOOL:
tp_str += "bool"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_MAP_INT:
@@ -372,18 +364,41 @@ def main():
print("Can't find", vars_dict_reverse[tp])
assert 0
- args_wash.append((name, tp_str, comment))
+ args_wash.append((name, default_value, tp_str, comment))
return args_wash
# end get_args_wash
+ args_in_wash = get_args_wash(args_in, args_in_index, False)
+
+ fw(".. function:: %s(bm, %s)\n\n" % (b[0], ", ".join([print_arg_in(arg) for arg in args_in_wash])))
+
+ # -- wash the comment
+ comment_washed = []
+ comment = [] if comment is None else comment
+ for i, l in enumerate(comment):
+ assert ((l.strip() == "") or
+ (l in {"/*", " *"}) or
+ (l.startswith(("/* ", " * "))))
+
+ l = l[3:]
+ if i == 0 and not l.strip():
+ continue
+ if l.strip():
+ l = " " + l
+ comment_washed.append(l)
+
+ fw("\n".join(comment_washed))
+ fw("\n")
+ # -- done
+
+
# all ops get this arg
fw(" :arg bm: The bmesh to operate on.\n")
fw(" :type bm: :class:`bmesh.types.BMesh`\n")
- args_in_wash = get_args_wash(args_in, args_in_index, False)
args_out_wash = get_args_wash(args_out, args_out_index, True)
- for (name, tp, comment) in args_in_wash:
+ for (name, _, tp, comment) in args_in_wash:
if comment == "":
comment = "Undocumented."
@@ -393,7 +408,7 @@ def main():
if args_out_wash:
fw(" :return:\n\n")
- for (name, tp, comment) in args_out_wash:
+ for (name, _, tp, comment) in args_out_wash:
assert name.endswith(".out")
name = name[:-4]
fw(" - ``%s``: %s\n\n" % (name, comment))
@@ -408,6 +423,11 @@ def main():
del fout
print(OUT_RST)
+def print_arg_in(arg):
+ (name, default_value, _, _) = arg
+ if default_value is None:
+ return name
+ return name + '=' + default_value
if __name__ == "__main__":
main()
diff --git a/source/blender/bmesh/intern/bmesh_opdefines.c b/source/blender/bmesh/intern/bmesh_opdefines.c
index 7424fdb9247..1c8bd3bd54e 100644
--- a/source/blender/bmesh/intern/bmesh_opdefines.c
+++ b/source/blender/bmesh/intern/bmesh_opdefines.c
@@ -1373,7 +1373,7 @@ static BMOpDefine bmo_duplicate_def = {
"duplicate",
/* slots_in */
{{"geom", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT | BM_EDGE | BM_FACE}}, /* input geometry */
- {"dest", BMO_OP_SLOT_PTR, {(int)BMO_OP_SLOT_SUBTYPE_PTR_BMESH}}, /* destination bmesh, if NULL will use current on */
+ {"dest", BMO_OP_SLOT_PTR, {(int)BMO_OP_SLOT_SUBTYPE_PTR_BMESH}}, /* destination bmesh, if None will use current on */
{"use_select_history", BMO_OP_SLOT_BOOL},
{"use_edge_flip_from_face", BMO_OP_SLOT_BOOL},
{{'\0'}},
@@ -1405,7 +1405,7 @@ static BMOpDefine bmo_split_def = {
"split",
/* slots_in */
{{"geom", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT | BM_EDGE | BM_FACE}}, /* input geometry */
- {"dest", BMO_OP_SLOT_PTR, {(int)BMO_OP_SLOT_SUBTYPE_PTR_BMESH}}, /* destination bmesh, if NULL will use current one */
+ {"dest", BMO_OP_SLOT_PTR, {(int)BMO_OP_SLOT_SUBTYPE_PTR_BMESH}}, /* destination bmesh, if None will use current one */
{"use_only_faces", BMO_OP_SLOT_BOOL}, /* when enabled. don't duplicate loose verts/edges */
{{'\0'}},
},
@@ -1780,7 +1780,7 @@ static BMOpDefine bmo_bevel_def = {
bmo_enum_bevel_miter_type}, /* outer miter kind */
{"spread", BMO_OP_SLOT_FLT}, /* amount to offset beveled edge */
{"smoothresh", BMO_OP_SLOT_FLT}, /* for passing mesh's smoothresh, used in hardening */
- {"custom_profile", BMO_OP_SLOT_PTR, {(int)BMO_OP_SLOT_SUBTYPE_PTR_STRUCT}}, /* CurveProfile */
+ {"custom_profile", BMO_OP_SLOT_PTR, {(int)BMO_OP_SLOT_SUBTYPE_PTR_STRUCT}}, /* CurveProfile, if None ignored */
{"vmesh_method", BMO_OP_SLOT_INT, {(int)BMO_OP_SLOT_SUBTYPE_INT_ENUM},
bmo_enum_bevel_vmesh_method}, /* The method to use to create meshes at intersections. */
{{'\0'}},
More information about the Bf-blender-cvs
mailing list