bartvdbraak/blender
1
0
Fork 4
Code Issues 4 Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity
427dbaed14
blender/doc/python_api/rst_from_bmesh_opdefines.py
Campbell Barton e955c94ed3 License Headers: Set copyright to "Blender Authors", add AUTHORS 
Listing the "Blender Foundation" as copyright holder implied the Blender
Foundation holds copyright to files which may include work from many
developers.

While keeping copyright on headers makes sense for isolated libraries,
Blender's own code may be refactored or moved between files in a way
that makes the per file copyright holders less meaningful.

Copyright references to the "Blender Foundation" have been replaced with
"Blender Authors", with the exception of `./extern/` since these this
contains libraries which are more isolated, any changed to license
headers there can be handled on a case-by-case basis.

Some directories in `./intern/` have also been excluded:

- `./intern/cycles/` it's own `AUTHORS` file is planned.
- `./intern/opensubdiv/`.

An "AUTHORS" file has been added, using the chromium projects authors
file as a template.

Design task: #110784

Ref !110783.
2023-08-16 00:20:26 +10:00

439 lines
15 KiB
Python
Raw Blame History

# SPDX-FileCopyrightText: 2012-2022 Blender Authors
#
# SPDX-License-Identifier: GPL-2.0-or-later
# This is a quite stupid script which extracts bmesh api docs from
# 'bmesh_opdefines.cc' in order to avoid having to add a lot of introspection
# data access into the api.
#
# The script is stupid because it makes assumptions about formatting...
# that each arg has its own line, that comments above or directly after will be __doc__ etc...
#
# We may want to replace this script with something else one day but for now its good enough.
# if it needs large updates it may be better to rewrite using a real parser or
# add introspection into bmesh.ops.
# - campbell
import os
import re
CURRENT_DIR = os.path.abspath(os.path.dirname(__file__))
SOURCE_DIR = os.path.normpath(os.path.abspath(os.path.normpath(os.path.join(CURRENT_DIR, "..", ".."))))
FILE_OP_DEFINES_CC = os.path.join(SOURCE_DIR, "source", "blender", "bmesh", "intern", "bmesh_opdefines.cc")
OUT_RST = os.path.join(CURRENT_DIR, "rst", "bmesh.ops.rst")
HEADER = r"""
BMesh Operators (bmesh.ops)
===========================
.. module:: bmesh.ops
This module gives access to low level bmesh operations.
Most operators take input and return output, they can be chained together
to perform useful operations.
Operator Example
++++++++++++++++
This script shows how operators can be used to model a link of a chain.
.. literalinclude:: __/examples/bmesh.ops.1.py
"""
def main():
fsrc = open(FILE_OP_DEFINES_CC, 'r', encoding="utf-8")
blocks = []
is_block = False
is_comment = False # /* global comments only */
comment_ctx = None
block_ctx = None
for l in fsrc:
l = l[:-1]
# weak but ok
if (
(("BMOpDefine" in l and l.split()[1] == "BMOpDefine") and "bmo_opdefines[]" not in l) or
("static BMO_FlagSet " in l)
):
is_block = True
block_ctx = []
blocks.append((comment_ctx, block_ctx))
elif l.strip().startswith("/*"):
is_comment = True
comment_ctx = []
if is_block:
if l.strip().startswith("//"):
pass
else:
# remove c++ comment if we have one
cpp_comment = l.find("//")
if cpp_comment != -1:
l = l[:cpp_comment]
# remove sentinel from enums
l = l.replace("{0, NULL}", "")
block_ctx.append(l)
if l.strip().endswith("};"):
is_block = False
comment_ctx = None
if is_comment:
c_comment_start = l.find("/*")
if c_comment_start != -1:
l = l[c_comment_start + 2:]
c_comment_end = l.find("*/")
if c_comment_end != -1:
l = l[:c_comment_end]
is_comment = False
comment_ctx.append(l)
fsrc.close()
del fsrc
# namespace hack
vars = (
"BMO_OP_SLOT_ELEMENT_BUF",
"BMO_OP_SLOT_BOOL",
"BMO_OP_SLOT_FLT",
"BMO_OP_SLOT_INT",
"BMO_OP_SLOT_MAT",
"BMO_OP_SLOT_VEC",
"BMO_OP_SLOT_PTR",
"BMO_OP_SLOT_MAPPING",
"BMO_OP_SLOT_SUBTYPE_MAP_ELEM",
"BMO_OP_SLOT_SUBTYPE_MAP_BOOL",
"BMO_OP_SLOT_SUBTYPE_MAP_INT",
"BMO_OP_SLOT_SUBTYPE_MAP_FLT",
"BMO_OP_SLOT_SUBTYPE_MAP_EMPTY",
"BMO_OP_SLOT_SUBTYPE_MAP_INTERNAL",
"BMO_OP_SLOT_SUBTYPE_PTR_BMESH",
"BMO_OP_SLOT_SUBTYPE_PTR_SCENE",
"BMO_OP_SLOT_SUBTYPE_PTR_OBJECT",
"BMO_OP_SLOT_SUBTYPE_PTR_MESH",
"BMO_OP_SLOT_SUBTYPE_PTR_STRUCT",
"BMO_OP_SLOT_SUBTYPE_INT_ENUM",
"BMO_OP_SLOT_SUBTYPE_INT_FLAG",
"BMO_OP_SLOT_SUBTYPE_ELEM_IS_SINGLE",
"BM_VERT",
"BM_EDGE",
"BM_FACE",
"BMO_OPTYPE_FLAG_NORMALS_CALC",
"BMO_OPTYPE_FLAG_UNTAN_MULTIRES",
"BMO_OPTYPE_FLAG_SELECT_FLUSH",
"BMO_OPTYPE_FLAG_SELECT_VALIDATE",
"BMO_OPTYPE_FLAG_NOP",
)
vars_dict = {}
for i, v in enumerate(vars):
vars_dict[v] = (1 << i)
globals().update(vars_dict)
# reverse lookup
vars_dict_reverse = {v: k for k, v in vars_dict.items()}
# end namespace hack
blocks_py = []
for comment, b in blocks:
# magic, translate into python
b[0] = b[0].replace("static BMOpDefine ", "")
is_enum = False
for i, l in enumerate(b):
l = l.strip()
# casts
l = l.replace("(int)", "")
l = re.sub(r'to_subtype_union\((.*?)\)', '{\\1}', l)
l = re.sub(r'eBMOpSlotSubType_Elem\((.*?)\)', '\\1', l)
l = l.replace("{", "(")
l = l.replace("}", ")")
if l.startswith("/*"):
l = l.replace("/*", "'''own <")
else:
l = l.replace("/*", "'''inline <")
l = l.replace("*/", ">''',")
# exec func. eg: bmo_rotate_edges_exec,
if l.startswith("bmo_") and l.endswith("_exec,"):
l = "None,"
# enums
if l.startswith("static BMO_FlagSet "):
is_enum = True
b[i] = l
# for l in b:
# print(l)
if is_enum:
text = "".join(b)
text = text.replace("static BMO_FlagSet ", "")
text = text.replace("[]", "")
text = text.strip(";")
text = text.replace("(", "[").replace(")", "]")
text = text.replace("\"", "'")
k, v = text.split("=", 1)
v = repr(re.findall(r"'([^']*)'", v))
k = k.strip()
v = v.strip()
vars_dict[k] = v
continue
text = "\n".join(b)
global_namespace = {
"__file__": "generated",
"__name__": "__main__",
}
global_namespace.update(vars_dict)
text_a, text_b = text.split("=", 1)
text = "result = " + text_b
exec(compile(text, "generated", 'exec'), global_namespace)
# print(global_namespace["result"])
blocks_py.append((comment, global_namespace["result"]))
# ---------------------
# Now convert into rst.
fout = open(OUT_RST, 'w', encoding="utf-8")
fw = fout.write
fw(HEADER)
for comment, b in blocks_py:
args_in = None
args_out = None
for member in b[1:]:
if type(member) == tuple:
if args_in is None:
args_in = member
elif args_out is None:
args_out = member
break
args_in_index = []
args_out_index = []
if args_in is not None:
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]
# get the args
def get_args_wash(args, args_index, is_ret):
args_wash = []
for i in args_index:
arg = args[i]
if len(arg) == 4:
name, tp, tp_sub, enums = arg
elif len(arg) == 3:
name, tp, tp_sub = arg
elif len(arg) == 2:
name, tp = arg
tp_sub = None
else:
print(arg)
assert 0
tp_str = ""
comment_prev = ""
comment_next = ""
if i != 0:
comment_prev = args[i + 1]
if type(comment_prev) == str and comment_prev.startswith("our <"):
comment_prev = comment_next[5:-1] # strip inline <...>
else:
comment_prev = ""
if i + 1 < len(args):
comment_next = args[i + 1]
if type(comment_next) == str and comment_next.startswith("inline <"):
comment_next = comment_next[8:-1] # strip inline <...>
else:
comment_next = ""
comment = ""
if comment_prev:
comment += comment_prev.strip()
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:
default_value = enums.split(",", 1)[0].strip("[")
tp_str = "enum in " + enums + ", default " + default_value
elif tp_sub == BMO_OP_SLOT_SUBTYPE_INT_FLAG:
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:
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:
tp_str = ":class:`bpy.types.Scene`"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_PTR_OBJECT:
tp_str = ":class:`bpy.types.Object`"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_PTR_MESH:
tp_str = ":class:`bpy.types.Mesh`"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_PTR_STRUCT:
# XXX Used for CurveProfile only currently I think (bevel code),
# but think the idea is that that pointer is for any type?
tp_str = ":class:`bpy.types.bpy_struct`"
else:
print("Can't find", vars_dict_reverse[tp_sub])
assert 0
elif tp == BMO_OP_SLOT_ELEMENT_BUF:
assert tp_sub is not None
ls = []
if tp_sub & BM_VERT:
ls.append(":class:`bmesh.types.BMVert`")
if tp_sub & BM_EDGE:
ls.append(":class:`bmesh.types.BMEdge`")
if tp_sub & BM_FACE:
ls.append(":class:`bmesh.types.BMFace`")
assert ls # Must be at least one.
if tp_sub & BMO_OP_SLOT_SUBTYPE_ELEM_IS_SINGLE:
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:
tp_str += "int"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_MAP_FLT:
tp_str += "float"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_MAP_ELEM:
tp_str += ":class:`bmesh.types.BMVert`/:class:`bmesh.types.BMEdge`/:class:`bmesh.types.BMFace`"
elif tp_sub == BMO_OP_SLOT_SUBTYPE_MAP_INTERNAL:
tp_str += "unknown internal data, not compatible with python"
else:
print("Can't find", vars_dict_reverse[tp_sub])
assert 0
else:
print("Can't find", vars_dict_reverse[tp])
assert 0
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([arg_name_with_default(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_out_wash = get_args_wash(args_out, args_out_index, True)
for (name, _, tp, comment) in args_in_wash:
if comment == "":
comment = "Undocumented."
fw(" :arg %s: %s\n" % (name, comment))
fw(" :type %s: %s\n" % (name, tp))
if args_out_wash:
fw(" :return:\n\n")
for (name, _, tp, comment) in args_out_wash:
assert name.endswith(".out")
name = name[:-4]
fw(" - ``%s``: %s\n\n" % (name, comment))
fw(" **type** %s\n" % tp)
fw("\n")
fw(" :rtype: dict with string keys\n")
fw("\n\n")
fout.close()
del fout
print(OUT_RST)
def arg_name_with_default(arg):
name, default_value, _, _ = arg
if default_value is None:
return name
return name + '=' + default_value
if __name__ == "__main__":
main()
Reference in New Issue View Git Blame Copy Permalink