griefith/test
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

PyDoc: use Python's type annotation syntax for doc-strings

Browse Source 
Replace plain-text type information with the type syntax used
for Python's type annotations as it's more concise, especially for
callbacks which often didn't include useful type information.

Note that this change only applies to inline doc-strings,
generated doc-strings from RNA need to be updated separately.

Details:

- Many minor corrections were made when "list" was incorrectly used
  instead of "sequence".
- Some type information wasn't defined in the doc-strings and has been
  added.
- Verbose type info would benefit from support for type aliases.
This commit is contained in:
Campbell Barton
2024-11-03 15:42:19 +11:00
parent 3347aa4017
commit 3bcfb151c1
90 changed files with 722 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
scripts/modules/addon_utils.py
View File

@@ -248,9 +248,9 @@ def check(module_name):
Returns the loaded state of the addon.
:arg module_name: The name of the addon and module.
:type module_name: string
:type module_name: str
:return: (loaded_default, loaded_state)
:rtype: tuple of booleans
:rtype: tuple[bool, bool]
"""
import sys
loaded_default = module_name in _preferences.addons
@@ -309,15 +309,15 @@ def enable(module_name, *, default_set=False, persistent=False, handle_error=Non
Enables an addon by name.
:arg module_name: the name of the addon and module.
:type module_name: string
:type module_name: str
:arg default_set: Set the user-preference.
:type default_set: bool
:arg persistent: Ensure the addon is enabled for the entire session (after loading new files).
:type persistent: bool
:arg handle_error: Called in the case of an error, taking an exception argument.
:type handle_error: function
:type handle_error: Callable[[Exception], None] | None
:return: the loaded module or None on failure.
:rtype: module
:rtype: ModuleType
"""
import os
@@ -511,11 +511,11 @@ def disable(module_name, *, default_set=False, handle_error=None):
Disables an addon by name.
:arg module_name: The name of the addon and module.
:type module_name: string
:type module_name: str
:arg default_set: Set the user-preference.
:type default_set: bool
:arg handle_error: Called in the case of an error, taking an exception argument.
:type handle_error: function
:type handle_error: Callable[[Exception], None] | None
"""
import sys
@@ -1381,9 +1381,9 @@ def _extension_module_name_decompose(package):
Returns the repository module name and the extensions ID from an extensions module name (``__package__``).
:arg module_name: The extensions module name.
:type module_name: string
:type module_name: str
:return: (repo_module_name, extension_id)
:rtype: tuple of strings
:rtype: tuple[str, str]
"""
if not package.startswith(_ext_base_pkg_idname_with_dot):
raise ValueError("The \"package\" does not name an extension")

4
scripts/modules/bl_app_template_utils.py
View File

@@ -84,10 +84,10 @@ def _disable(template_id, *, handle_error=None):
Disables a template by name.
:arg template_id: The name of the template and module.
:type template_id: string
:type template_id: str
:arg handle_error: Called in the case of an error,
taking an exception argument.
:type handle_error: function
:type handle_error: Callable[[Exception], None] | None
"""
if handle_error is None:

4
scripts/modules/bl_console_utils/autocomplete/complete_calltip.py
View File

@@ -138,9 +138,9 @@ def complete(line, cursor, namespace):
:arg cursor: current character position
:type cursor: int
:arg namespace: namespace
:type namespace: dict
:type namespace: dict[str, Any]
:returns: (matches, world, scrollback)
:rtype: (list of str, str, str)
:rtype: tuple[str, str, str]
>>> import os
>>> complete('os.path.isdir(', 14, {'os': os})[-1]

6
scripts/modules/bl_console_utils/autocomplete/complete_import.py
View File

@@ -40,7 +40,7 @@ def get_root_modules():
folders of the python-path.
:returns: modules
:rtype: list
:rtype: list[ModuleType]
"""
global ROOT_MODULES
modules = []
@@ -80,7 +80,7 @@ def module_list(path):
:arg path: folder path
:type path: str
:returns: modules
:rtype: list
:rtype: list[ModuleType]
"""
if os.path.isdir(path):
@@ -117,7 +117,7 @@ def complete(line):
:type line: str
:returns: list of completion possibilities
:rtype: list
:rtype: list[str]
>>> complete('import weak')
['weakref']

2
scripts/modules/bl_console_utils/autocomplete/complete_namespace.py
View File

@@ -32,7 +32,7 @@ def complete_names(word, namespace):
:arg word: word to be completed
:type word: str
:arg namespace: namespace
:type namespace: dict
:type namespace: dict[str, Any]
:returns: completion matches
:rtype: list of str

4
scripts/modules/bl_console_utils/autocomplete/intellisense.py
View File

@@ -54,7 +54,7 @@ def complete(line, cursor, namespace, private):
:arg private: whether private variables should be listed
:type private: bool
:returns: list of completions, word
:rtype: list, str
:rtype: tuple[list[str], str]
>>> complete('re.sr', 5, {'re': re})
(['re.sre_compile', 're.sre_parse'], 're.sr')
@@ -89,7 +89,7 @@ def expand(line, cursor, namespace, *, private=True):
:arg cursor: current character position
:type cursor: int
:arg namespace: namespace
:type namespace: dict
:type namespace: dict[str, Any]
:arg private: whether private variables should be listed
:type private: bool
:returns:

64
scripts/modules/bpy/path.py
View File

@@ -47,12 +47,12 @@ def abspath(path, *, start=None, library=None):
:arg start: Relative to this path,
when not set the current filename is used.
:type start: string or bytes
:type start: str | bytes
:arg library: The library this path is from. This is only included for
convenience, when the library is not None its path replaces *start*.
:type library: :class:`bpy.types.Library`
:return: The absolute path.
:rtype: string
:rtype: str
"""
if isinstance(path, bytes):
if path.startswith(b"//"):
@@ -83,12 +83,12 @@ def relpath(path, *, start=None):
Returns the path relative to the current blend file using the "//" prefix.
:arg path: An absolute path.
:type path: string or bytes
:type path: str | bytes
:arg start: Relative to this path,
when not set the current filename is used.
:type start: string or bytes
:type start: str | bytes
:return: The relative path.
:rtype: string
:rtype: str
"""
if isinstance(path, bytes):
if not path.startswith(b"//"):
@@ -110,9 +110,9 @@ def is_subdir(path, directory):
Both paths must be absolute.
:arg path: An absolute path.
:type path: string or bytes
:type path: str | bytes
:return: Whether or not the path is a subdirectory.
:rtype: boolean
:rtype: bool
"""
from os.path import normpath, normcase, sep
path = normpath(normcase(path))
@@ -134,11 +134,11 @@ def clean_name(name, *, replace="_"):
or the *replace* argument if defined.
:arg name: The path name.
:type name: string or bytes
:type name: str | bytes
:arg replace: The replacement for non-valid characters.
:type replace: string
:type replace: str
:return: The cleaned name.
:rtype: string
:rtype: str
"""
if replace != "_":
@@ -206,13 +206,13 @@ def display_name(name, *, has_ext=True, title_case=True):
Intended for use with filenames and module names.
:arg name: The name to be used for displaying the user interface.
:type name: string
:type name: str
:arg has_ext: Remove file extension from name.
:type has_ext: boolean
:type has_ext: bool
:arg title_case: Convert lowercase names to title case.
:type title_case: boolean
:type title_case: bool
:return: The display string.
:rtype: string
:rtype: str
"""
if has_ext:
@@ -239,9 +239,9 @@ def display_name_to_filepath(name):
which aren't supported in a filepath.
:arg name: The display name to convert.
:type name: string
:type name: str
:return: The file path.
:rtype: string
:rtype: str
"""
for disp_value, file_value in _display_name_literals.items():
name = name.replace(disp_value, file_value)
@@ -254,9 +254,9 @@ def display_name_from_filepath(name):
ensured to be utf8 compatible.
:arg name: The file path to convert.
:type name: string
:type name: str
:return: The display name.
:rtype: string
:rtype: str
"""
name = _os.path.splitext(basename(name))[0]
@@ -270,9 +270,9 @@ def resolve_ncase(path):
returning a string with the path if found else return the original path.
:arg path: The path name to resolve.
:type path: string
:type path: str
:return: The resolved path.
:rtype: string
:rtype: str
"""
def _ncase_path_found(path):
@@ -335,14 +335,14 @@ def ensure_ext(filepath, ext, *, case_sensitive=False):
Return the path with the extension added if it is not already set.
:arg filepath: The file path.
:type filepath: string
:type filepath: str
:arg ext: The extension to check for, can be a compound extension. Should
start with a dot, such as '.blend' or '.tar.gz'.
:type ext: string
:type ext: str
:arg case_sensitive: Check for matching case when comparing extensions.
:type case_sensitive: boolean
:type case_sensitive: bool
:return: The file path with the given extension.
:rtype: string
:rtype: str
"""
if case_sensitive:
@@ -360,13 +360,13 @@ def module_names(path, *, recursive=False, package=""):
Return a list of modules which can be imported from *path*.
:arg path: a directory to scan.
:type path: string
:type path: str
:arg recursive: Also return submodule names for packages.
:type recursive: bool
:arg package: Optional string, used as the prefix for module names (without the trailing ".").
:type package: string
:type package: str
:return: a list of string pairs (module_name, module_file).
:rtype: list of strings
:rtype: list[str]
"""
from os.path import join, isfile
@@ -404,7 +404,7 @@ def basename(path):
Use for Windows compatibility.
:return: The base name of the given path.
:rtype: string
:rtype: str
"""
return _os.path.basename(path[2:] if path[:2] in {"//", b"//"} else path)
@@ -414,9 +414,9 @@ def native_pathsep(path):
Replace the path separator with the systems native ``os.sep``.
:arg path: The path to replace.
:type path: string
:type path: str
:return: The path with system native separators.
:rtype: string
:rtype: str
"""
if type(path) is str:
if _os.sep == "/":
@@ -443,9 +443,9 @@ def reduce_dirs(dirs):
(Useful for recursive path searching).
:arg dirs: Sequence of directory paths.
:type dirs: sequence of strings
:type dirs: Sequence[str]
:return: A unique list of paths.
:rtype: list of strings
:rtype: list[str]
"""
dirs = list({_os.path.normpath(_os.path.abspath(d)) for d in dirs})
dirs.sort(key=lambda d: len(d))

80
scripts/modules/bpy/utils/__init__.py
View File

@@ -91,9 +91,9 @@ def execfile(filepath, *, mod=None):
Execute a file path as a Python script.
:arg filepath: Path of the script to execute.
:type filepath: string
:type filepath: str
:arg mod: Optional cached module, the result of a previous execution.
:type mod: Module or None
:type mod: ModuleType | None
:return: The module which can be passed back in as ``mod``.
:rtype: ModuleType
"""
@@ -177,12 +177,12 @@ def modules_from_path(path, loaded_modules):
Load all modules in a path and return them as a list.
:arg path: this path is scanned for scripts and packages.
:type path: string
:type path: str
:arg loaded_modules: already loaded module names, files matching these
names will be ignored.
:type loaded_modules: set
:type loaded_modules: set[ModuleType]
:return: all loaded modules.
:rtype: list
:rtype: list[ModuleType]
"""
modules = []
@@ -409,7 +409,7 @@ def script_paths(*, subdir=None, user_pref=True, check_all=False, use_user=True,
Returns a list of valid script paths.
:arg subdir: Optional subdir.
:type subdir: string
:type subdir: str
:arg user_pref: Include the user preference script paths.
:type user_pref: bool
:arg check_all: Include local, user and system paths rather just the paths Blender uses.
@@ -419,7 +419,7 @@ def script_paths(*, subdir=None, user_pref=True, check_all=False, use_user=True,
:arg use_system_environment: Include BLENDER_SYSTEM_SCRIPTS variable path
:type use_system_environment: bool
:return: script paths.
:rtype: list
:rtype: list[str]
"""
if check_all or use_user:
@@ -500,9 +500,9 @@ def app_template_paths(*, path=None):
Returns valid application template paths.
:arg path: Optional subdir.
:type path: string
:return: app template paths.
:rtype: generator
:type path: str
:return: App template paths.
:rtype: Iterator[str]
"""
subdir_args = (path,) if path is not None else ()
# Note: keep in sync with: Blender's 'BKE_appdir_app_template_any'.
@@ -528,9 +528,9 @@ def preset_paths(subdir):
Returns a list of paths for a specific preset.
:arg subdir: preset subdirectory (must not be an absolute path).
:type subdir: string
:return: script paths.
:rtype: list
:type subdir: str
:return: Script paths.
:rtype: list[str]
"""
dirs = []
for path in script_paths(subdir="presets"):
@@ -566,7 +566,7 @@ def register_preset_path(path):
When the ``__init__.py`` is in the same location as a ``presets`` directory.
For example an operators preset would be located under: ``presets/operator/{operator.id}/``
where ``operator.id`` is the ``bl_idname`` of the operator.
:type path: string
:type path: str
:return: success
:rtype: bool
"""
@@ -585,7 +585,7 @@ def unregister_preset_path(path):
:arg path: preset directory (must be an absolute path).
This must match the registered path exactly.
:type path: string
:type path: str
:return: success
:rtype: bool
"""
@@ -677,9 +677,9 @@ def smpte_from_seconds(time, *, fps=None, fps_base=None):
If *fps* and *fps_base* are not given the current scene is used.
:arg time: time in seconds.
:type time: int, float or ``datetime.timedelta``.
:type time: int | float | datetime.timedelta
:return: the frame string.
:rtype: string
:rtype: str
"""
return smpte_from_frame(
@@ -697,9 +697,9 @@ def smpte_from_frame(frame, *, fps=None, fps_base=None):
If *fps* and *fps_base* are not given the current scene is used.
:arg frame: frame number.
:type frame: int or float.
:type frame: int | float
:return: the frame string.
:rtype: string
:rtype: str
"""
if fps is None:
@@ -730,7 +730,7 @@ def time_from_frame(frame, *, fps=None, fps_base=None):
If *fps* and *fps_base* are not given the current scene is used.
:arg frame: number.
:type frame: int or float.
:type frame: int | float
:return: the time in seconds.
:rtype: datetime.timedelta
"""
@@ -756,9 +756,9 @@ def time_to_frame(time, *, fps=None, fps_base=None):
If *fps* and *fps_base* are not given the current scene is used.
:arg time: time in seconds.
:type time: number or a ``datetime.timedelta`` object
:return: the frame.
:rtype: float
:type time: float | int | datetime.timedelta
:return: The frame.
:rtype: float | int | datetime.timedelta
"""
if fps is None:
@@ -859,13 +859,13 @@ def user_resource(resource_type, *, path="", create=False):
Return a user resource path (normally from the users home directory).
:arg resource_type: Resource type in ['DATAFILES', 'CONFIG', 'SCRIPTS', 'EXTENSIONS'].
:type resource_type: string
:type resource_type: str
:arg path: Optional subdirectory.
:type path: string
:type path: str
:arg create: Treat the path as a directory and create it if its not existing.
:type create: boolean
:type create: bool
:return: a path.
:rtype: string
:rtype: str
"""
target_path = _user_resource(resource_type, path=path)
@@ -901,13 +901,13 @@ def extension_path_user(package, *, path="", create=False):
to the repository (typically "System" repositories).
:arg package: The ``__package__`` of the extension.
:type package: string
:type package: str
:arg path: Optional subdirectory.
:type path: string
:type path: str
:arg create: Treat the path as a directory and create it if its not existing.
:type create: boolean
:type create: bool
:return: a path.
:rtype: string
:rtype: str
"""
from addon_utils import _extension_module_name_decompose
@@ -965,11 +965,11 @@ def register_submodule_factory(module_name, submodule_names):
unregistered in reverse order.
:arg module_name: The module name, typically ``__name__``.
:type module_name: string
:type module_name: str
:arg submodule_names: List of submodule names to load and unload.
:type submodule_names: list of strings
:type submodule_names: list[str]
:return: register and unregister functions.
:rtype: tuple pair of functions
:rtype: tuple[Callable[[], None], Callable[[], None]]
"""
module = None
@@ -1002,9 +1002,9 @@ def register_tool(tool_cls, *, after=None, separator=False, group=False):
Register a tool in the toolbar.
:arg tool_cls: A tool subclass.
:type tool_cls: :class:`bpy.types.WorkSpaceTool` subclass.
:type tool_cls: :class:`bpy.types.WorkSpaceTool`
:arg after: Optional identifiers this tool will be added after.
:type after: collection of strings or None.
:type after: Sequence[str] | None
:arg separator: When true, add a separator before this tool.
:type separator: bool
:arg group: When true, add a new nested group of tools.
@@ -1317,15 +1317,15 @@ def make_rna_paths(struct_name, prop_name, enum_name):
Create RNA "paths" from given names.
:arg struct_name: Name of a RNA struct (like e.g. "Scene").
:type struct_name: string
:type struct_name: str
:arg prop_name: Name of a RNA struct's property.
:type prop_name: string
:type prop_name: str
:arg enum_name: Name of a RNA enum identifier.
:type enum_name: string
:type enum_name: str
:return: A triple of three "RNA paths"
(most_complete_path, "struct.prop", "struct.prop:'enum'").
If no enum_name is given, the third element will always be void.
:rtype: tuple of strings
:rtype: tuple[str, str, str]
"""
src = src_rna = src_enum = ""
if struct_name:

12
scripts/modules/bpy_extras/anim_utils.py
View File

@@ -87,13 +87,13 @@ def bake_action(
:type obj: :class:`bpy.types.Object`
:arg action: An action to bake the data into, or None for a new action
to be created.
:type action: :class:`bpy.types.Action` or None
:type action: :class:`bpy.types.Action` | None
:arg frames: Frames to bake.
:type frames: iterable of int
:type frames: int
:arg bake_options: Options for baking.
:type bake_options: :class:`anim_utils.BakeOptions`
:return: an action or None
:rtype: :class:`bpy.types.Action`
:return: Action or None.
:rtype: :class:`bpy.types.Action` | None
"""
if not (bake_options.do_pose or bake_options.do_object):
return None
@@ -121,7 +121,7 @@ def bake_action_objects(
:type bake_options: :class:`anim_utils.BakeOptions`
:return: A sequence of Action or None types (aligned with `object_action_pairs`)
:rtype: sequence of :class:`bpy.types.Action`
:rtype: Sequence[:class:`bpy.types.Action`]
"""
if not (bake_options.do_pose or bake_options.do_object):
return []
@@ -180,7 +180,7 @@ def bake_action_iter(
:type obj: :class:`bpy.types.Object`
:arg action: An action to bake the data into, or None for a new action
to be created.
:type action: :class:`bpy.types.Action` or None
:type action: :class:`bpy.types.Action` | None
:arg bake_options: Boolean options of what to include into the action bake.
:type bake_options: :class:`anim_utils.BakeOptions`

2
scripts/modules/bpy_extras/bmesh_utils.py
View File

@@ -25,7 +25,7 @@ def bmesh_linked_uv_islands(bm, uv_layer):
:arg uv_layer: the UV layer to source UVs from.
:type bmesh: :class:`BMLayerItem`
:return: list of lists containing polygon indices
:rtype: list
:rtype: list[list[int]]
"""
result = []

8
scripts/modules/bpy_extras/image_utils.py
View File

@@ -26,10 +26,10 @@ def load_image(
:arg filepath: The image filename
If a path precedes it, this will be searched as well.
:type filepath: string
:type filepath: str
:arg dirname: is the directory where the image may be located - any file at
the end will be ignored.
:type dirname: string
:type dirname: str
:arg place_holder: if True a new place holder image will be created.
this is useful so later you can relink the image to its original data.
:type place_holder: bool
@@ -46,7 +46,7 @@ def load_image(
For formats blender can read, simply return the path that is given.
:type convert_callback: function
:arg relpath: If not None, make the file relative to this path.
:type relpath: None or string
:type relpath: str | None
:arg check_existing: If true,
returns already loaded image datablock if possible
(based on file path).
@@ -56,7 +56,7 @@ def load_image(
is also enabled).
:type force_reload: bool
:return: an image or None
:rtype: :class:`bpy.types.Image`
:rtype: :class:`bpy.types.Image` | None
"""
import os
import bpy

43
scripts/modules/bpy_extras/io_utils.py
View File

@@ -331,11 +331,11 @@ def axis_conversion_ensure(operator, forward_attr, up_attr):
:arg operator: the operator to access axis attributes from.
:type operator: :class:`bpy.types.Operator`
:arg forward_attr: attribute storing the forward axis
:type forward_attr: string
:type forward_attr: str
:arg up_attr: attribute storing the up axis
:type up_attr: string
:type up_attr: str
:return: True if the value was modified.
:rtype: boolean
:rtype: bool
"""
def validate(axis_forward, axis_up):
if axis_forward[-1] == axis_up[-1]:
@@ -362,10 +362,10 @@ def create_derived_objects(depsgraph, objects):
:arg depsgraph: The evaluated depsgraph.
:type depsgraph: :class:`bpy.types.Depsgraph`
:arg objects: A sequencer of objects.
:type objects: sequence of :class:`bpy.types.Object`
:return: A dictionary where each key is an object from `objects`,
values are lists of (:class:`bpy.types.Object`, :class:`mathutils.Matrix`) tuples representing instances.
:rtype: dict
:type objects: Sequence[:class:`bpy.types.Object`]
:return: A dictionary where each key is an object from ``objects``,
values are lists of (object, matrix) tuples representing instances.
:rtype: dict[:class:`bpy.types.Object`, list[tuple[:class:`bpy.types.Object`, :class:`mathutils.Matrix`]]]
"""
result = {}
for ob in objects:
@@ -463,25 +463,25 @@ def path_reference(
:arg filepath: the file path to return,
supporting blenders relative '//' prefix.
:type filepath: string
:type filepath: str
:arg base_src: the directory the *filepath* is relative too
(normally the blend file).
:type base_src: string
:type base_src: str
:arg base_dst: the directory the *filepath* will be referenced from
(normally the export path).
:type base_dst: string
:type base_dst: str
:arg mode: the method used get the path in
['AUTO', 'ABSOLUTE', 'RELATIVE', 'MATCH', 'STRIP', 'COPY']
:type mode: string
:type mode: str
:arg copy_subdir: the subdirectory of *base_dst* to use when mode='COPY'.
:type copy_subdir: string
:type copy_subdir: str
:arg copy_set: collect from/to pairs when mode='COPY',
pass to *path_reference_copy* when exporting is done.
:type copy_set: set
:type copy_set: set[tuple[str, str]]
:arg library: The library this path is relative to.
:type library: :class:`bpy.types.Library` or None
:type library: :class:`bpy.types.Library` | None
:return: the new filepath.
:rtype: string
:rtype: str
"""
import os
is_relative = filepath.startswith("//")
@@ -528,9 +528,9 @@ def path_reference_copy(copy_set, report=print):
Execute copying files of path_reference
:arg copy_set: set of (from, to) pairs to copy.
:type copy_set: set
:type copy_set: set[tuple[str, str]]
:arg report: function used for reporting warnings, takes a string argument.
:type report: function
:type report: Callable[[str], None]
"""
if not copy_set:
return
@@ -564,12 +564,13 @@ def unique_name(key, name, name_dict, name_max=-1, clean_func=None, sep="."):
Helper function for storing unique names which may have special characters
stripped and restricted to a maximum length.
:arg key: unique item this name belongs to, name_dict[key] will be reused
:arg key: Unique item this name belongs to, name_dict[key] will be reused
when available.
This can be the object, mesh, material, etc instance itself.
:type key: any hashable object associated with the *name*.
Any hashable object associated with the *name*.
:type key: Any
:arg name: The name used to create a unique value in *name_dict*.
:type name: string
:type name: str
:arg name_dict: This is used to cache namespace to ensure no collisions
occur, this should be an empty dict initially and only modified by this
function.
@@ -578,7 +579,7 @@ def unique_name(key, name, name_dict, name_max=-1, clean_func=None, sep="."):
:type clean_func: function
:arg sep: Separator to use when between the name and a number when a
duplicate name is found.
:type sep: string
:type sep: str
"""
name_new = name_dict.get(key)
if name_new is None:

33
scripts/modules/bpy_extras/mesh_utils.py
View File

@@ -20,7 +20,7 @@ def mesh_linked_uv_islands(mesh):
:arg mesh: the mesh used to group with.
:type mesh: :class:`bpy.types.Mesh`
:return: list of lists containing polygon indices
:rtype: list
:rtype: list[list[int]]
"""
if mesh.polygons and not mesh.uv_layers.active.data:
@@ -84,12 +84,12 @@ def mesh_linked_uv_islands(mesh):
def mesh_linked_triangles(mesh):
"""
Splits the mesh into connected triangles, use this for separating cubes from
other mesh elements within 1 mesh datablock.
other mesh elements within 1 mesh data-block.
:arg mesh: the mesh used to group with.
:type mesh: :class:`bpy.types.Mesh`
:return: lists of lists containing triangles.
:rtype: list
:return: Lists of lists containing triangles.
:rtype: list[list[:class:`bpy.types.MeshLoopTriangle`]]
"""
# Build vert face connectivity
@@ -139,9 +139,8 @@ def mesh_linked_triangles(mesh):
def edge_face_count_dict(mesh):
"""
:return: dict of edge keys with their value set to the number of
faces using each edge.
:rtype: dict
:return: Dictionary of edge keys with their value set to the number of faces using each edge.
:rtype: dict[tuple[int, int], int]
"""
face_edge_count = {}
@@ -161,7 +160,7 @@ def edge_face_count_dict(mesh):
def edge_face_count(mesh):
"""
:return: list face users for each item in mesh.edges.
:rtype: list
:rtype: list[int]
"""
edge_face_count = edge_face_count_dict(mesh)
get = dict.get
@@ -237,12 +236,12 @@ def ngon_tessellate(from_data, indices, fix_loops=True, debug_print=True):
index lists. Designed to be used for importers that need indices for an
ngon to create from existing verts.
:arg from_data: either a mesh, or a list/tuple of vectors.
:type from_data: list or :class:`bpy.types.Mesh`
:arg from_data: Either a mesh, or a list/tuple of 3D vectors.
:type from_data: :class:`bpy.types.Mesh` | list[Sequence[float]] | tuple[Sequence[float]]
:arg indices: a list of indices to use this list
is the ordered closed poly-line
to fill, and can be a subset of the data given.
:type indices: list
:type indices: list[int]
:arg fix_loops: If this is enabled poly-lines
that use loops to make multiple
poly-lines are dealt with correctly.
@@ -428,12 +427,12 @@ def triangle_random_points(num_points, loop_triangles):
"""
Generates a list of random points over mesh loop triangles.
:arg num_points: the number of random points to generate on each triangle.
:type int:
:arg loop_triangles: list of the triangles to generate points on.
:type loop_triangles: :class:`bpy.types.MeshLoopTriangle`, sequence
:return: list of random points over all triangles.
:rtype: list
:arg num_points: The number of random points to generate on each triangle.
:type num_points: int
:arg loop_triangles: Sequence of the triangles to generate points on.
:type loop_triangles: Sequence[:class:`bpy.types.MeshLoopTriangle`]
:return: List of random points over all triangles.
:rtype: list[:class:`mathutils.Vector`]
"""
from random import random

6
scripts/modules/bpy_extras/object_utils.py
View File

@@ -89,12 +89,12 @@ def object_data_add(context, obdata, operator=None, name=None):
:arg context: The context to use.
:type context: :class:`bpy.types.Context`
:arg obdata: the data used for the new object.
:type obdata: valid object data type or None.
:arg obdata: Valid object data to used for the new object or None.
:type obdata: :class:`bpy.types.ID` | None
:arg operator: The operator, checked for location and rotation properties.
:type operator: :class:`bpy.types.Operator`
:arg name: Optional name
:type name: string
:type name: str
:return: the newly created object in the scene.
:rtype: :class:`bpy.types.Object`
"""

8
scripts/modules/bpy_extras/view3d_utils.py
View File

@@ -66,12 +66,12 @@ def region_2d_to_origin_3d(region, rv3d, coord, *, clamp=None):
:type region: :class:`bpy.types.Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:type rv3d: :class:`bpy.types.RegionView3D`
:arg coord: 2d coordinates relative to the region;
:arg coord: 2D coordinates relative to the region;
(event.mouse_region_x, event.mouse_region_y) for example.
:type coord: 2d vector
:type coord: Sequence[float]
:arg clamp: Clamp the maximum far-clip value used.
(negative value will move the offset away from the view_location)
:type clamp: float or None
:type clamp: float | None
:return: The origin of the viewpoint in 3d space.
:rtype: :class:`mathutils.Vector`
"""
@@ -164,7 +164,7 @@ def location_3d_to_region_2d(region, rv3d, coord, *, default=None):
:arg default: Return this value if ``coord``
is behind the origin of a perspective view.
:return: 2d location
:rtype: :class:`mathutils.Vector` or ``default`` argument.
:rtype: :class:`mathutils.Vector` | Any
"""
from mathutils import Vector

36
scripts/modules/bpy_types.py
View File

@@ -25,9 +25,9 @@ class Context(_StructRNA):
Returns the property from the path, raise an exception when not found.
:arg path: patch which this property resolves.
:type path: string
:type path: str
:arg coerce: optional argument, when True, the property will be converted into its Python representation.
:type coerce: boolean
:type coerce: bool
"""
# This is a convenience wrapper around `_StructRNA.path_resolve` which doesn't support accessing context members.
# Without this wrapper many users were writing `exec("context.{:s}".format(data_path))` which is a security
@@ -606,7 +606,7 @@ class Mesh(_types.ID):
float triplets each representing (X, Y, Z)
eg: [(0.0, 1.0, 0.5), ...].
:type vertices: iterable object
:type vertices: Iterable[Sequence[float]]
:arg edges:
int pairs, each pair contains two indices to the
@@ -614,13 +614,13 @@ class Mesh(_types.ID):
When an empty iterable is passed in, the edges are inferred from the polygons.
:type edges: iterable object
:type edges: Iterable[Sequence[int]]
:arg faces:
iterator of faces, each faces contains three or more indices to
the *vertices* argument. eg: [(5, 6, 8, 9), (1, 2, 3), ...]
:type faces: iterable object
:type faces: Iterable[Sequence[int]]
.. warning::
@@ -855,7 +855,7 @@ class Gizmo(_StructRNA):
Draw a shape created form :class:`Gizmo.draw_custom_shape`.
:arg shape: The cached shape to draw.
:type shape: Undefined.
:type shape: Any
:arg matrix: 4x4 matrix, when not given :class:`Gizmo.matrix_world` is used.
:type matrix: :class:`mathutils.Matrix`
:arg select_id: The selection id.
@@ -896,11 +896,11 @@ class Gizmo(_StructRNA):
Create a new shape that can be passed to :class:`Gizmo.draw_custom_shape`.
:arg type: The type of shape to create in (POINTS, LINES, TRIS, LINE_STRIP).
:type type: string
:arg verts: Coordinates.
:type verts: sequence of 2D or 3D coordinates.
:return: The newly created shape.
:rtype: Undefined (it may change).
:type type: str
:arg verts: Sequence of 2D or 3D coordinates.
:type verts: Sequence[Sequence[float]]
:return: The newly created shape (the return type make change).
:rtype: Any
"""
import gpu
from gpu.types import (
@@ -972,7 +972,7 @@ class Macro(_StructRNA):
Append an operator to a registered macro class.
:arg operator: Identifier of the operator. This does not have to be defined when this function is called.
:type operator: string
:type operator: str
:return: The operator macro for property access.
:rtype: :class:`OperatorMacro`
"""
@@ -1113,20 +1113,20 @@ class Menu(_StructRNA, _GenericUI, metaclass=_RNAMeta):
Populate a menu from a list of paths.
:arg searchpaths: Paths to scan.
:type searchpaths: sequence of strings.
:type searchpaths: Sequence[str]
:arg operator: The operator id to use with each file.
:type operator: string
:type operator: str
:arg prop_filepath: Optional operator filepath property (defaults to "filepath").
:type prop_filepath: string
:type prop_filepath: str
:arg props_default: Properties to assign to each operator.
:type props_default: dict
:type props_default: dict[str, Any]
:arg filter_ext: Optional callback that takes the file extensions.
Returning false excludes the file from the list.
:type filter_ext: Callable that takes a string and returns a bool.
:type filter_ext: Callable[[str], bool] | None
:arg display_name: Optional callback that takes the full path, returns the name to display.
:type display_name: Callable that takes a string and returns a string.
:type display_name: Callable[[str], str]
"""
layout = self.layout

4
scripts/modules/gpu_extras/batch.py
View File

@@ -16,7 +16,9 @@ def batch_for_shader(shader, type, content, *, indices=None):
:arg type: "'POINTS', 'LINES', 'TRIS' or 'LINES_ADJ'".
:type type: str
:arg content: Maps the name of the shader attribute with the data to fill the vertex buffer.
:type content: dict
For the dictionary values see documentation for :class:`gpu.types.GPUVertBuf.attr_fill` data argument.
:type content: dict[str, Buffer | Sequence[float] | Sequence[int] | \
Sequence[Sequence[float]] | Sequence[Sequence[int]]]
:return: compatible batch
:rtype: :class:`gpu.types.GPUBatch`
"""

10
scripts/modules/gpu_extras/presets.py
View File

@@ -6,16 +6,16 @@ def draw_circle_2d(position, color, radius, *, segments=None):
"""
Draw a circle.
:arg position: Position where the circle will be drawn.
:type position: 2D Vector
:arg color: Color of the circle. To use transparency GL_BLEND has to be enabled.
:type color: tuple containing RGBA values
:arg position: 2D position where the circle will be drawn.
:type position: Sequence[float]
:arg color: Color of the circle (RGBA). To use transparency GL_BLEND has to be enabled.
:type color: Sequence[float]
:arg radius: Radius of the circle.
:type radius: float
:arg segments: How many segments will be used to draw the circle.
Higher values give better results but the drawing will take longer.
If None or not specified, an automatic value will be calculated.
:type segments: int or None
:type segments: int | None
"""
from math import sin, cos, pi, ceil, acos
import gpu

2
scripts/modules/rna_info.py
View File

@@ -381,7 +381,7 @@ class InfoPropertyRNA:
"""
:arg enum_descr_override: Optionally override items for enum.
Otherwise expand the literal items.
:type enum_descr_override: string or None when unset.
:type enum_descr_override: str | None
"""
type_str = ""
if self.fixed_type is None:

10
scripts/startup/bl_operators/bone_selection_sets.py
View File

@@ -310,11 +310,11 @@ class POSE_OT_selection_set_paste(_PoseModeOnlyMixin, Operator):
def _uniqify(name, other_names):
"""
:arg name: The name to make unique.
:type name: string
:type name: str
:arg other_names: The name to make unique.
:type other_names: string
:type other_names: str
:return: Return a unique name with ``.xxx`` suffix if necessary.
:rtype: string
:rtype: str
Example usage:
@@ -362,7 +362,7 @@ def _to_json(context):
plus any with the is_selected checkbox on.
:return: The selection as JSON data.
:rtype: string
:rtype: str
"""
import json
@@ -382,7 +382,7 @@ def _from_json(context, as_json):
"""Add the selection sets (one or more) from JSON to the current rig.
:arg as_json: The JSON contents to load.
:type as_json: string
:type as_json: str
"""
import json

10
scripts/startup/bl_operators/uvcalc_transform.py
View File

@@ -58,7 +58,7 @@ def is_island_uv_selected(island, uv_layer, any_edge):
Returns True if the island is UV selected.
:arg island: list of faces to query.
:type island: sequence of :class:`BMFace`.
:type island: Sequence[:class:`BMFace`]
:arg uv_layer: the UV layer to source UVs from.
:type bmesh: :class:`BMLayerItem`
:arg any_edge: use edge selection instead of vertex selection.
@@ -77,10 +77,10 @@ def island_uv_bounds(island, uv_layer):
The UV bounds of UV island.
:arg island: list of faces to query.
:type island: sequence of :class:`BMFace`.
:type island: Sequence[:class:`BMFace`]
:arg uv_layer: the UV layer to source UVs from.
:return: U-min, V-min, U-max, V-max.
:rtype: list
:rtype: list[float]
"""
minmax = [1e30, 1e30, -1e30, -1e30]
for face in island:
@@ -98,10 +98,10 @@ def island_uv_bounds_center(island, uv_layer):
The UV bounds center of UV island.
:arg island: list of faces to query.
:type island: sequence of :class:`BMFace`.
:type island: Sequence[:class:`BMFace`]
:arg uv_layer: the UV layer to source UVs from.
:return: U, V center.
:rtype: tuple
:rtype: tuple[float, float]
"""
minmax = island_uv_bounds(island, uv_layer)
return (

2
scripts/startup/bl_ui/generic_ui_list.py
View File

@@ -63,7 +63,7 @@ def draw_ui_list(
:type menu_class_name: str
:returns: The right side column.
:rtype: :class:`UILayout`.
:rtype: :class:`UILayout`
Additional keyword arguments are passed to :class:`UIList.template_list`.
"""