ilusha/blender
1
0
Fork 0
mirror of https://github.com/blender/blender synced 2026-09-29 04:37:17 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

PyDoc: use :param: instead of :arg: in Sphinx docstrings

Browse source 
While "arg" isn't deprecated "param" is preferred and used in all
Sphinx's examples & tutorials.

Ref !154039
This commit is contained in:
Campbell Barton 2026-02-07 09:03:36 +11:00
parent 40298aa015
commit 791505e2ed
96 changed files with 1131 additions and 1120 deletions
Download patch file Download diff file Expand all files Collapse all files

18
scripts/modules/_bl_console_utils/autocomplete/complete_calltip.py
View file

@ -31,7 +31,7 @@ RE_DEF_COMPLETE = re.compile(
def reduce_newlines(text):
"""Reduces multiple newlines to a single newline.
:arg text: text with multiple newlines
:param text: text with multiple newlines
:type text: str
:returns: text with single newlines
:rtype: str
@ -45,7 +45,7 @@ def reduce_newlines(text):
def reduce_spaces(text):
"""Reduces multiple white-spaces to a single space.
:arg text: text with multiple spaces
:param text: text with multiple spaces
:type text: str
:returns: text with single spaces
:rtype: str
@ -59,7 +59,7 @@ def reduce_spaces(text):
def get_doc(obj):
"""Get the doc string or comments for an object.
:arg object: object
:param object: object
:returns: doc string
:rtype: str
@ -73,11 +73,11 @@ def get_doc(obj):
def get_argspec(func, *, strip_self=True, doc=None, source=None):
"""Get argument specifications.
:arg strip_self: strip ``self`` from argspec
:param strip_self: strip ``self`` from argspec
:type strip_self: bool
:arg doc: doc string of func (optional)
:param doc: doc string of func (optional)
:type doc: str
:arg source: source code of func (optional)
:param source: source code of func (optional)
:type source: str
:returns: argument specification
:rtype: str
@ -133,11 +133,11 @@ def get_argspec(func, *, strip_self=True, doc=None, source=None):
def complete(line, cursor, namespace):
"""Complete callable with call-tip.
:arg line: incomplete text line
:param line: incomplete text line
:type line: str
:arg cursor: current character position
:param cursor: current character position
:type cursor: int
:arg namespace: namespace
:param namespace: namespace
:type namespace: dict[str, Any]
:returns: (matches, world, scrollback)
:rtype: tuple[str, str, str]

4
scripts/modules/_bl_console_utils/autocomplete/complete_import.py
View file

@ -77,7 +77,7 @@ def module_list(path):
Return the list containing the names of the modules available in
the given folder.
:arg path: folder path
:param path: folder path
:type path: str
:returns: modules
:rtype: list[ModuleType]
@ -108,7 +108,7 @@ def complete(line):
"""
Returns a list containing the completion possibilities for an import line.
:arg line:
:param line:
incomplete line which contains an import statement::

18
scripts/modules/_bl_console_utils/autocomplete/complete_namespace.py
View file

@ -29,9 +29,9 @@ def is_struct_seq(obj):
def complete_names(word, namespace):
"""Complete variable names or attributes
:arg word: word to be completed
:param word: word to be completed
:type word: str
:arg namespace: namespace
:param namespace: namespace
:type namespace: dict[str, Any]
:returns: completion matches
:rtype: list of str
@ -52,12 +52,12 @@ def complete_indices(word, namespace, *, obj=None, base=None):
* integer numbers for list
* any keys for dictionary
:arg word: word to be completed
:param word: word to be completed
:type word: str
:arg namespace: namespace
:param namespace: namespace
:type namespace: dict
:arg obj: object evaluated from base
:arg base: sub-string which can be evaluated into an object.
:param obj: object evaluated from base
:param base: sub-string which can be evaluated into an object.
:type base: str
:returns: completion matches
:rtype: list of str
@ -105,11 +105,11 @@ def complete(word, namespace, *, private=True):
"""Complete word within a namespace with the standard rlcompleter
module. Also supports index or key access [].
:arg word: word to be completed
:param word: word to be completed
:type word: str
:arg namespace: namespace
:param namespace: namespace
:type namespace: dict
:arg private: whether private attribute/methods should be returned
:param private: whether private attribute/methods should be returned
:type private: bool
:returns: completion matches
:rtype: list of str

16
scripts/modules/_bl_console_utils/autocomplete/intellisense.py
View file

@ -45,13 +45,13 @@ def complete(line, cursor, namespace, private):
* index completion for lists and dictionaries
* module completion (from/import)
:arg line: incomplete text line
:param line: incomplete text line
:type line: str
:arg cursor: current character position
:param cursor: current character position
:type cursor: int
:arg namespace: namespace
:param namespace: namespace
:type namespace: dict
:arg private: whether private variables should be listed
:param private: whether private variables should be listed
:type private: bool
:returns: list of completions, word
:rtype: tuple[list[str], str]
@ -84,13 +84,13 @@ def expand(line, cursor, namespace, *, private=True):
"""This method is invoked when the user asks auto-completion,
e.g. when Ctrl+Space is clicked.
:arg line: incomplete text line
:param line: incomplete text line
:type line: str
:arg cursor: current character position
:param cursor: current character position
:type cursor: int
:arg namespace: namespace
:param namespace: namespace
:type namespace: dict[str, Any]
:arg private: whether private variables should be listed
:param private: whether private variables should be listed
:type private: bool
:returns:

4
scripts/modules/_bpy_internal/extensions/wheel_manager.py
View file

@ -543,12 +543,12 @@ def apply_action(
debug: bool,
) -> None:
"""
:arg local_dir:
:param local_dir:
The location wheels are stored.
Typically: ``~/.config/blender/4.2/extensions/.local``.
WARNING: files under this directory may be removed.
:arg local_dir_site_packages:
:param local_dir_site_packages:
The path which wheels are extracted into.
Typically: ``~/.config/blender/4.2/extensions/.local/lib/python3.11/site-packages``.
"""

40
scripts/modules/_bpy_types.py
View file

@ -24,9 +24,9 @@ class Context(_StructRNA):
"""
Returns the property from the path, raise an exception when not found.
:arg path: patch which this property resolves.
:param path: patch which this property resolves.
:type path: str
:arg coerce: optional argument, when True, the property will be converted into its Python representation.
:param coerce: optional argument, when True, the property will be converted into its Python representation.
:type coerce: bool
"""
# This is a convenience wrapper around `_StructRNA.path_resolve` which doesn't support accessing
@ -597,11 +597,11 @@ class EditBone(_StructRNA, _GenericBone, metaclass=_StructMetaPropGroup):
Transform the bones head, tail, roll and envelope
(when the matrix has a scale component).
:arg matrix: 3x3 or 4x4 transformation matrix.
:param matrix: 3x3 or 4x4 transformation matrix.
:type matrix: :class:`mathutils.Matrix`
:arg scale: Scale the bone envelope by the matrix.
:param scale: Scale the bone envelope by the matrix.
:type scale: bool
:arg roll:
:param roll:
Correct the roll to point in the same relative
direction to the head and tail.
@ -684,13 +684,13 @@ class Mesh(_types.ID):
Make a mesh from a list of vertices/edges/faces
Until we have a nicer way to make geometry, use this.
:arg vertices:
:param vertices:
float triplets each representing (X, Y, Z)
eg: [(0.0, 1.0, 0.5), ...].
:type vertices: Iterable[Sequence[float]]
:arg edges:
:param edges:
int pairs, each pair contains two indices to the
*vertices* argument. eg: [(1, 2), ...]
@ -698,7 +698,7 @@ class Mesh(_types.ID):
When an empty iterable is passed in, the edges are inferred from the polygons.
:type edges: Iterable[Sequence[int]]
:arg faces:
:param faces:
iterator of faces, each faces contains three or more indices to
the *vertices* argument. eg: [(5, 6, 8, 9), (1, 2, 3), ...]
@ -941,11 +941,11 @@ class Gizmo(_StructRNA):
"""
Draw a shape created form :class:`Gizmo.draw_custom_shape`.
:arg shape: The cached shape to draw.
:param shape: The cached shape to draw.
:type shape: Any
:arg matrix: 4x4 matrix, when not given :class:`Gizmo.matrix_world` is used.
:param matrix: 4x4 matrix, when not given :class:`Gizmo.matrix_world` is used.
:type matrix: :class:`mathutils.Matrix`
:arg select_id: The selection id.
:param select_id: The selection id.
Only use when drawing within :class:`Gizmo.draw_select`.
:type select_id: int
"""
@ -982,9 +982,9 @@ 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).
:param type: The type of shape to create in (POINTS, LINES, TRIS, LINE_STRIP).
:type type: str
:arg verts: Sequence of 2D or 3D coordinates.
:param verts: Sequence of 2D or 3D coordinates.
:type verts: Sequence[Sequence[float]]
:return: The newly created shape (the return type make change).
:rtype: Any
@ -1063,7 +1063,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.
:param operator: Identifier of the operator. This does not have to be defined when this function is called.
:type operator: str
:return: The operator macro for property access.
:rtype: :class:`OperatorMacro`
@ -1214,20 +1214,20 @@ class Menu(_StructRNA, _GenericUI, metaclass=_RNAMeta):
"""
Populate a menu from a list of paths.
:arg searchpaths: Paths to scan.
:param searchpaths: Paths to scan.
:type searchpaths: Sequence[str]
:arg operator: The operator id to use with each file.
:param operator: The operator id to use with each file.
:type operator: str
:arg prop_filepath: Optional operator filepath property (defaults to "filepath").
:param prop_filepath: Optional operator filepath property (defaults to "filepath").
:type prop_filepath: str
:arg props_default: Properties to assign to each operator.
:param props_default: Properties to assign to each operator.
:type props_default: dict[str, Any]
:arg filter_ext: Optional callback that takes the file extensions.
:param filter_ext: Optional callback that takes the file extensions.
Returning false excludes the file from the list.
:type filter_ext: Callable[[str], bool] | None
:arg display_name: Optional callback that takes the full path, returns the name to display.
:param display_name: Optional callback that takes the full path, returns the name to display.
:type display_name: Callable[[str], str]
"""

2
scripts/modules/_rna_info.py
View file

@ -403,7 +403,7 @@ class InfoPropertyRNA:
enum_descr_override=None,
):
"""
:arg enum_descr_override: Optionally override items for enum.
:param enum_descr_override: Optionally override items for enum.
Otherwise expand the literal items.
:type enum_descr_override: str | None
"""

26
scripts/modules/addon_utils.py
View file

@ -252,7 +252,7 @@ def check(module_name):
"""
Returns the loaded state of the addon.
:arg module_name: The name of the addon and module.
:param module_name: The name of the addon and module.
:type module_name: str
:return: (loaded_default, loaded_state)
:rtype: tuple[bool, bool]
@ -313,17 +313,17 @@ def enable(module_name, *, default_set=False, persistent=False, refresh_handled=
"""
Enables an addon by name.
:arg module_name: the name of the addon and module.
:param module_name: the name of the addon and module.
:type module_name: str
:arg default_set: Set the user-preference.
:param 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).
:param persistent: Ensure the addon is enabled for the entire session (after loading new files).
:type persistent: bool
:arg refresh_handled: When true, :func:`extensions_refresh` must have been called with ``module_name``
:param refresh_handled: When true, :func:`extensions_refresh` must have been called with ``module_name``
included in ``addon_modules_pending``.
This should be used to avoid many calls to refresh extensions when enabling multiple add-ons at once.
:type refresh_handled: bool
:arg handle_error: Called in the case of an error, taking an exception argument.
:param handle_error: Called in the case of an error, taking an exception argument.
:type handle_error: Callable[[Exception], None] | None
:return: the loaded module or None on failure.
:rtype: ModuleType
@ -539,11 +539,11 @@ def disable(module_name, *, default_set=False, refresh_handled=False, handle_err
"""
Disables an addon by name.
:arg module_name: The name of the addon and module.
:param module_name: The name of the addon and module.
:type module_name: str
:arg default_set: Set the user-preference.
:param default_set: Set the user-preference.
:type default_set: bool
:arg handle_error: Called in the case of an error, taking an exception argument.
:param handle_error: Called in the case of an error, taking an exception argument.
:type handle_error: Callable[[Exception], None] | None
"""
import sys
@ -1425,7 +1425,7 @@ _ext_manifest_filename_toml = "blender_manifest.toml"
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.
# :param module_name: The extensions module name.
# :type module_name: str
# :return: (repo_module_name, extension_id)
# :rtype: tuple[str, str]
@ -1852,12 +1852,12 @@ def extensions_refresh(
Ensure data relating to extensions is up to date.
This should be called after extensions on the file-system have changed.
:arg ensure_wheels: When true, refresh installed wheels with wheels used by extensions.
:param ensure_wheels: When true, refresh installed wheels with wheels used by extensions.
:type ensure_wheels: bool
:arg addon_modules_pending: Refresh these add-ons by listing their package names, as if they are enabled.
:param addon_modules_pending: Refresh these add-ons by listing their package names, as if they are enabled.
This is needed so wheels can be setup before the add-on is enabled.
:type addon_modules_pending: Sequence[str] | None
:arg handle_error: Called in the case of an error, taking an exception argument.
:param handle_error: Called in the case of an error, taking an exception argument.
:type handle_error: Callable[[Exception], None] | None
"""

4
scripts/modules/bl_app_template_utils.py
View file

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

42
scripts/modules/bpy/path.py
View file

@ -45,10 +45,10 @@ def abspath(path, *, start=None, library=None):
Returns the absolute path relative to the current blend file
using the "//" prefix.
:arg start: Relative to this path,
:param start: Relative to this path,
when not set the current filename is used.
:type start: str | bytes
:arg library: The library this path is from. This is only included for
:param 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.
@ -82,9 +82,9 @@ def relpath(path, *, start=None):
"""
Returns the path relative to the current blend file using the "//" prefix.
:arg path: An absolute path.
:param path: An absolute path.
:type path: str | bytes
:arg start: Relative to this path,
:param start: Relative to this path,
when not set the current filename is used.
:type start: str | bytes
:return: The relative path.
@ -109,7 +109,7 @@ def is_subdir(path, directory):
Returns true if *path* in a subdirectory of *directory*.
Both paths must be absolute.
:arg path: An absolute path.
:param path: An absolute path.
:type path: str | bytes
:return: Whether or not the path is a subdirectory.
:rtype: bool
@ -133,9 +133,9 @@ def clean_name(name, *, replace="_"):
All characters besides A-Z/a-z, 0-9 are replaced with "_"
or the *replace* argument if defined.
:arg name: The path name.
:param name: The path name.
:type name: str | bytes
:arg replace: The replacement for non-valid characters.
:param replace: The replacement for non-valid characters.
:type replace: str
:return: The cleaned name.
:rtype: str
@ -205,11 +205,11 @@ def display_name(name, *, has_ext=True, title_case=True):
Creates a display string from name to be used menus and the user interface.
Intended for use with filenames and module names.
:arg name: The name to be used for displaying the user interface.
:param name: The name to be used for displaying the user interface.
:type name: str
:arg has_ext: Remove file extension from name.
:param has_ext: Remove file extension from name.
:type has_ext: bool
:arg title_case: Convert lowercase names to title case.
:param title_case: Convert lowercase names to title case.
:type title_case: bool
:return: The display string.
:rtype: str
@ -238,7 +238,7 @@ def display_name_to_filepath(name):
Performs the reverse of display_name using literal versions of characters
which aren't supported in a filepath.
:arg name: The display name to convert.
:param name: The display name to convert.
:type name: str
:return: The file path.
:rtype: str
@ -253,7 +253,7 @@ def display_name_from_filepath(name):
Returns the path stripped of directory and extension,
ensured to be utf8 compatible.
:arg name: The file path to convert.
:param name: The file path to convert.
:type name: str
:return: The display name.
:rtype: str
@ -269,7 +269,7 @@ def resolve_ncase(path):
Resolve a case insensitive path on a case sensitive system,
returning a string with the path if found else return the original path.
:arg path: The path name to resolve.
:param path: The path name to resolve.
:type path: str
:return: The resolved path.
:rtype: str
@ -334,12 +334,12 @@ 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.
:param filepath: The file path.
:type filepath: str
:arg ext: The extension to check for, can be a compound extension. Should
:param ext: The extension to check for, can be a compound extension. Should
start with a dot, such as ``.blend`` or ``.tar.gz``.
:type ext: str
:arg case_sensitive: Check for matching case when comparing extensions.
:param case_sensitive: Check for matching case when comparing extensions.
:type case_sensitive: bool
:return: The file path with the given extension.
:rtype: str
@ -359,11 +359,11 @@ def module_names(path, *, recursive=False, package=""):
"""
Return a list of modules which can be imported from *path*.
:arg path: a directory to scan.
:param path: a directory to scan.
:type path: str
:arg recursive: Also return submodule names for packages.
:param recursive: Also return submodule names for packages.
:type recursive: bool
:arg package: Optional string, used as the prefix for module names (without the trailing ".").
:param package: Optional string, used as the prefix for module names (without the trailing ".").
:type package: str
:return: a list of string pairs (module_name, module_file).
:rtype: list[tuple[str, str]]
@ -413,7 +413,7 @@ def native_pathsep(path):
"""
Replace the path separator with the systems native ``os.sep``.
:arg path: The path to replace.
:param path: The path to replace.
:type path: str
:return: The path with system native separators.
:rtype: str
@ -442,7 +442,7 @@ def reduce_dirs(dirs):
any directories nested in one of the other paths.
(Useful for recursive path searching).
:arg dirs: Sequence of directory paths.
:param dirs: Sequence of directory paths.
:type dirs: Sequence[str]
:return: A unique list of paths.
:rtype: list[str]

78
scripts/modules/bpy/utils/__init__.py
View file

@ -92,9 +92,9 @@ def execfile(filepath, *, mod=None):
"""
Execute a file path as a Python script.
:arg filepath: Path of the script to execute.
:param filepath: Path of the script to execute.
:type filepath: str
:arg mod: Optional cached module, the result of a previous execution.
:param mod: Optional cached module, the result of a previous execution.
:type mod: ModuleType | None
:return: The module which can be passed back in as ``mod``.
:rtype: ModuleType
@ -178,9 +178,9 @@ 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.
:param path: this path is scanned for scripts and packages.
:type path: str
:arg loaded_modules: already loaded module names, files matching these
:param loaded_modules: already loaded module names, files matching these
names will be ignored.
:type loaded_modules: set[ModuleType]
:return: all loaded modules.
@ -232,13 +232,13 @@ def load_scripts(*, reload_scripts=False, refresh_scripts=False, extensions=True
"""
Load scripts and run each modules register function.
:arg reload_scripts: Causes all scripts to have their unregister method
:param reload_scripts: Causes all scripts to have their unregister method
called before loading.
:type reload_scripts: bool
:arg refresh_scripts: only load scripts which are not already loaded
:param refresh_scripts: only load scripts which are not already loaded
as modules.
:type refresh_scripts: bool
:arg extensions: Loads additional scripts (add-ons & app-templates).
:param extensions: Loads additional scripts (add-ons & app-templates).
:type extensions: bool
"""
use_time = use_class_register_check = _bpy.app.debug_python
@ -380,7 +380,7 @@ def load_scripts_extensions(*, reload_scripts=False):
"""
Load extensions scripts (add-ons and app-templates)
:arg reload_scripts: Causes all scripts to have their unregister method
:param reload_scripts: Causes all scripts to have their unregister method
called before loading.
:type reload_scripts: bool
"""
@ -428,15 +428,15 @@ 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.
:param subdir: Optional subdir.
:type subdir: str
:arg user_pref: Include the user preference script paths.
:param 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.
:param check_all: Include local, user and system paths rather just the paths Blender uses.
:type check_all: bool
:arg use_user: Include user paths
:param use_user: Include user paths
:type use_user: bool
:arg use_system_environment: Include BLENDER_SYSTEM_SCRIPTS variable path
:param use_system_environment: Include BLENDER_SYSTEM_SCRIPTS variable path
:type use_system_environment: bool
:return: script paths.
:rtype: list[str]
@ -519,7 +519,7 @@ def app_template_paths(*, path=None):
"""
Returns valid application template paths.
:arg path: Optional subdir.
:param path: Optional subdir.
:type path: str
:return: App template paths.
:rtype: Iterator[str]
@ -547,7 +547,7 @@ def preset_paths(subdir):
"""
Returns a list of paths for a specific preset.
:arg subdir: preset subdirectory (must not be an absolute path).
:param subdir: preset subdirectory (must not be an absolute path).
:type subdir: str
:return: Script paths.
:rtype: list[str]
@ -578,7 +578,7 @@ def register_preset_path(path):
"""
Register a preset search path.
:arg path: preset directory (must be an absolute path).
:param path: preset directory (must be an absolute path).
This path must contain a "presets" subdirectory which will typically contain presets for add-ons.
@ -602,7 +602,7 @@ def unregister_preset_path(path):
"""
Unregister a preset search path.
:arg path: preset directory (must be an absolute path).
:param path: preset directory (must be an absolute path).
This must match the registered path exactly.
:type path: str
@ -646,7 +646,7 @@ def is_path_builtin(path):
"""
Returns True if the path is one of the built-in paths used by Blender.
:arg path: Path you want to check if it is in the built-in settings directory
:param path: Path you want to check if it is in the built-in settings directory
:type path: str
:rtype: bool
"""
@ -674,7 +674,7 @@ def is_path_extension(path):
"""
Returns True if the path is from an extensions repository.
:arg path: Path to check if it is within an extension repository.
:param path: Path to check if it is within an extension repository.
:type path: str
:rtype: bool
"""
@ -696,7 +696,7 @@ 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.
:param time: time in seconds.
:type time: int | float | datetime.timedelta
:return: the frame string.
:rtype: str
@ -716,7 +716,7 @@ 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.
:param frame: frame number.
:type frame: int | float
:return: the frame string.
:rtype: str
@ -749,7 +749,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.
:param frame: number.
:type frame: int | float
:return: the time in seconds.
:rtype: datetime.timedelta
@ -775,7 +775,7 @@ 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.
:param time: time in seconds.
:type time: float | int | datetime.timedelta
:return: The frame.
:rtype: float | int | datetime.timedelta
@ -878,11 +878,11 @@ 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'].
:param resource_type: Resource type in ['DATAFILES', 'CONFIG', 'SCRIPTS', 'EXTENSIONS'].
:type resource_type: str
:arg path: Optional subdirectory.
:param path: Optional subdirectory.
:type path: str
:arg create: Treat the path as a directory and create it if its not existing.
:param create: Treat the path as a directory and create it if its not existing.
:type create: bool
:return: a path.
:rtype: str
@ -920,11 +920,11 @@ def extension_path_user(package, *, path="", create=False):
because it is cleared each upgrade and the users may not have write permissions
to the repository (typically "System" repositories).
:arg package: The ``__package__`` of the extension.
:param package: The ``__package__`` of the extension.
:type package: str
:arg path: Optional subdirectory.
:param path: Optional subdirectory.
:type path: str
:arg create: Treat the path as a directory and create it if its not existing.
:param create: Treat the path as a directory and create it if its not existing.
:type create: bool
:return: a path.
:rtype: str
@ -962,7 +962,7 @@ def register_classes_factory(classes):
Utility function to create register and unregister functions
which simply registers and unregisters a sequence of classes.
:arg classes: Sequence of classes to register and unregister.
:param classes: Sequence of classes to register and unregister.
:type classes: Sequence[type]
:return: register and unregister functions.
:rtype: tuple[Callable[[], None], Callable[[], None]]
@ -989,9 +989,9 @@ def register_submodule_factory(module_name, submodule_names):
Modules are registered in the order given,
unregistered in reverse order.
:arg module_name: The module name, typically ``__name__``.
:param module_name: The module name, typically ``__name__``.
:type module_name: str
:arg submodule_names: List of submodule names to load and unload.
:param submodule_names: List of submodule names to load and unload.
:type submodule_names: list[str]
:return: register and unregister functions.
:rtype: tuple[Callable[[], None], Callable[[], None]]
@ -1026,13 +1026,13 @@ def register_tool(tool_cls, *, after=None, separator=False, group=False):
"""
Register a tool in the toolbar.
:arg tool_cls: A tool subclass.
:param tool_cls: A tool subclass.
:type tool_cls: type[:class:`bpy.types.WorkSpaceTool`]
:arg after: Optional identifiers this tool will be added after.
:param after: Optional identifiers this tool will be added after.
:type after: Sequence[str] | set[str] | None
:arg separator: When true, add a separator before this tool.
:param separator: When true, add a separator before this tool.
:type separator: bool
:arg group: When true, add a new nested group of tools.
:param group: When true, add a new nested group of tools.
:type group: bool
"""
space_type = tool_cls.bl_space_type
@ -1341,11 +1341,11 @@ 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").
:param struct_name: Name of a RNA struct (like e.g. "Scene").
:type struct_name: str
:arg prop_name: Name of a RNA struct's property.
:param prop_name: Name of a RNA struct's property.
:type prop_name: str
:arg enum_name: Name of a RNA enum identifier.
:param enum_name: Name of a RNA enum identifier.
:type enum_name: str
:return: A triple of three "RNA paths"
(most_complete_path, "struct.prop", "struct.prop:'enum'").

2
scripts/modules/bpy/utils/previews.py
View file

@ -118,7 +118,7 @@ def remove(pcoll):
"""
Remove the specified previews collection.
:arg pcoll: Preview collection to close.
:param pcoll: Preview collection to close.
:type pcoll: :class:`ImagePreviewCollection`
"""
pcoll.close()

26
scripts/modules/bpy_extras/anim_utils.py
View file

@ -154,14 +154,14 @@ def bake_action(
bake_options,
):
"""
:arg obj: Object to bake.
:param obj: Object to bake.
:type obj: :class:`bpy.types.Object`
:arg action: An action to bake the data into, or None for a new action
:param action: An action to bake the data into, or None for a new action
to be created.
:type action: :class:`bpy.types.Action` | None
:arg frames: Frames to bake.
:param frames: Frames to bake.
:type frames: int
:arg bake_options: Options for baking.
:param bake_options: Options for baking.
:type bake_options: :class:`anim_utils.BakeOptions`
:return: Action or None.
:rtype: :class:`bpy.types.Action` | None
@ -186,9 +186,9 @@ def bake_action_objects(
"""
A version of :func:`bake_action_objects_iter` that takes frames and returns the output.
:arg frames: Frames to bake.
:param frames: Frames to bake.
:type frames: iterable of int
:arg bake_options: Options for baking.
:param bake_options: Options for baking.
:type bake_options: :class:`anim_utils.BakeOptions`
:return: A sequence of Action or None types (aligned with ``object_action_pairs``)
@ -211,10 +211,10 @@ def bake_action_objects_iter(
"""
An coroutine that bakes actions for multiple objects.
:arg object_action_pairs: Sequence of object action tuples,
:param object_action_pairs: Sequence of object action tuples,
action is the destination for the baked data. When None a new action will be created.
:type object_action_pairs: Sequence of (:class:`bpy.types.Object`, :class:`bpy.types.Action`)
:arg bake_options: Options for baking.
:param bake_options: Options for baking.
:type bake_options: :class:`anim_utils.BakeOptions`
"""
scene = bpy.context.scene
@ -247,12 +247,12 @@ def bake_action_iter(
"""
An coroutine that bakes action for a single object.
:arg obj: Object to bake.
:param obj: Object to bake.
:type obj: :class:`bpy.types.Object`
:arg action: An action to bake the data into, or None for a new action
:param action: An action to bake the data into, or None for a new action
to be created.
:type action: :class:`bpy.types.Action` | None
:arg bake_options: Boolean options of what to include into the action bake.
:param bake_options: Boolean options of what to include into the action bake.
:type bake_options: :class:`anim_utils.BakeOptions`
:return: an action or None
@ -724,7 +724,7 @@ class KeyframesCo:
Assumes the action is new, that it has no F-curves. Otherwise, the only difference between versions is
performance and implementation simplicity.
:arg group_name: Name of the Group that F-curves are added to.
:param group_name: Name of the Group that F-curves are added to.
"""
linear_enum_values = [
bpy.types.Keyframe.bl_rna.properties["interpolation"].enum_items["LINEAR"].value
@ -756,7 +756,7 @@ class KeyframesCo:
Assumes the action already exists, that it might already have F-curves. Otherwise, the
only difference between versions is performance and implementation simplicity.
:arg lookup_fcurves: : This is only used for efficiency.
:param lookup_fcurves: : This is only used for efficiency.
It's a substitute for ``channelbag.fcurves.find()`` which is a potentially expensive linear search.
"""
linear_enum_values = [

4
scripts/modules/bpy_extras/bmesh_utils.py
View file

@ -20,9 +20,9 @@ def bmesh_linked_uv_islands(bm, uv_layer):
For meshes use :class:`bpy.types.Mesh.mesh_linked_uv_islands` instead.
:arg bm: the bmesh used to group with.
:param bm: the bmesh used to group with.
:type bmesh: :class:`BMesh`
:arg uv_layer: the UV layer to source UVs from.
:param uv_layer: the UV layer to source UVs from.
:type bmesh: :class:`BMLayerItem`
:return: list of lists containing polygon indices
:rtype: list[list[int]]

4
scripts/modules/bpy_extras/id_map_utils.py
View file

@ -31,9 +31,9 @@ def get_all_referenced_ids(id, ref_map):
"""
Return a set of IDs directly or indirectly referenced by id.
:arg id: Datablock whose references we're interested in.
:param id: Datablock whose references we're interested in.
:type id: bpy.types.ID
:arg ref_map: The global ID reference map, retrieved from get_id_reference_map()
:param ref_map: The global ID reference map, retrieved from get_id_reference_map()
:type ref_map: dict[bpy.types.ID, set[bpy.types.ID]]
:return: Set of datablocks referenced by `id`.
:rtype: set[bpy.types.ID]

18
scripts/modules/bpy_extras/image_utils.py
View file

@ -24,34 +24,34 @@ def load_image(
Return an image from the file path with options to search multiple paths
and return a placeholder if its not found.
:arg filepath: The image filename
:param filepath: The image filename
If a path precedes it, this will be searched as well.
:type filepath: str
:arg dirname: is the directory where the image may be located - any file at
:param dirname: is the directory where the image may be located - any file at
the end will be ignored.
:type dirname: str
:arg place_holder: if True a new place holder image will be created.
:param 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
:arg recursive: If True, directories will be recursively searched.
:param recursive: If True, directories will be recursively searched.
Be careful with this if you have files in your root directory because
it may take a long time.
:type recursive: bool
:arg ncase_cmp: on non windows systems, find the correct case for the file.
:param ncase_cmp: on non windows systems, find the correct case for the file.
:type ncase_cmp: bool
:arg convert_callback: a function that takes an existing path and returns
:param convert_callback: a function that takes an existing path and returns
a new one. Use this when loading image formats blender may not support,
the CONVERT_CALLBACK can take the path for a GIF (for example),
convert it to a PNG and return the PNG's path.
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.
:param relpath: If not None, make the file relative to this path.
:type relpath: str | None
:arg check_existing: If true,
:param check_existing: If true,
returns already loaded image data-block if possible
(based on file path).
:type check_existing: bool
:arg force_reload: If true,
:param force_reload: If true,
force reloading of image (only useful when ``check_existing``
is also enabled).
:type force_reload: bool

38
scripts/modules/bpy_extras/io_utils.py
View file

@ -342,11 +342,11 @@ def axis_conversion_ensure(operator, forward_attr, up_attr):
Function to ensure an operator has valid axis conversion settings, intended
to be used from :class:`bpy.types.Operator.check`.
:arg operator: the operator to access axis attributes from.
:param operator: the operator to access axis attributes from.
:type operator: :class:`bpy.types.Operator`
:arg forward_attr: attribute storing the forward axis
:param forward_attr: attribute storing the forward axis
:type forward_attr: str
:arg up_attr: attribute storing the up axis
:param up_attr: attribute storing the up axis
:type up_attr: str
:return: True if the value was modified.
:rtype: bool
@ -373,9 +373,9 @@ def create_derived_objects(depsgraph, objects):
"""
This function takes a sequence of objects, returning their instances.
:arg depsgraph: The evaluated depsgraph.
:param depsgraph: The evaluated depsgraph.
:type depsgraph: :class:`bpy.types.Depsgraph`
:arg objects: A sequencer of objects.
:param objects: A sequencer of objects.
: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.
@ -475,24 +475,24 @@ def path_reference(
Return a filepath relative to a destination directory, for use with
exporters.
:arg filepath: the file path to return,
:param filepath: the file path to return,
supporting blenders relative '//' prefix.
:type filepath: str
:arg base_src: the directory the *filepath* is relative too
:param base_src: the directory the *filepath* is relative too
(normally the blend file).
:type base_src: str
:arg base_dst: the directory the *filepath* will be referenced from
:param base_dst: the directory the *filepath* will be referenced from
(normally the export path).
:type base_dst: str
:arg mode: the method used get the path in
:param mode: the method used get the path in
['AUTO', 'ABSOLUTE', 'RELATIVE', 'MATCH', 'STRIP', 'COPY']
:type mode: str
:arg copy_subdir: the subdirectory of *base_dst* to use when mode='COPY'.
:param copy_subdir: the subdirectory of *base_dst* to use when mode='COPY'.
:type copy_subdir: str
:arg copy_set: collect from/to pairs when mode='COPY',
:param copy_set: collect from/to pairs when mode='COPY',
pass to *path_reference_copy* when exporting is done.
:type copy_set: set[tuple[str, str]]
:arg library: The library this path is relative to.
:param library: The library this path is relative to.
:type library: :class:`bpy.types.Library` | None
:return: the new filepath.
:rtype: str
@ -542,9 +542,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.
:param copy_set: set of (from, to) pairs to copy.
:type copy_set: set[tuple[str, str]]
:arg report: function used for reporting warnings, takes a string argument.
:param report: function used for reporting warnings, takes a string argument.
:type report: Callable[[str], None]
"""
if not copy_set:
@ -579,20 +579,20 @@ 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
:param 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.
Any hashable object associated with the *name*.
:type key: Any
:arg name: The name used to create a unique value in *name_dict*.
:param name: The name used to create a unique value in *name_dict*.
:type name: str
:arg name_dict: This is used to cache namespace to ensure no collisions
:param 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.
:type name_dict: dict
:arg clean_func: Function to call on *name* before creating a unique value.
:param clean_func: Function to call on *name* before creating a unique value.
:type clean_func: function
:arg sep: Separator to use when between the name and a number when a
:param sep: Separator to use when between the name and a number when a
duplicate name is found.
:type sep: str
"""

14
scripts/modules/bpy_extras/mesh_utils.py
View file

@ -17,7 +17,7 @@ def mesh_linked_uv_islands(mesh):
"""
Returns lists of polygon indices connected by UV islands.
:arg mesh: the mesh used to group with.
:param mesh: the mesh used to group with.
:type mesh: :class:`bpy.types.Mesh`
:return: list of lists containing polygon indices
:rtype: list[list[int]]
@ -86,7 +86,7 @@ def mesh_linked_triangles(mesh):
Splits the mesh into connected triangles, use this for separating cubes from
other mesh elements within 1 mesh data-block.
:arg mesh: the mesh used to group with.
:param mesh: the mesh used to group with.
:type mesh: :class:`bpy.types.Mesh`
:return: Lists of lists containing triangles.
:rtype: list[list[:class:`bpy.types.MeshLoopTriangle`]]
@ -236,13 +236,13 @@ 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 3D vectors.
:param 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
:param 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[int]
:arg fix_loops: If this is enabled poly-lines
:param fix_loops: If this is enabled poly-lines
that use loops to make multiple
poly-lines are dealt with correctly.
:type fix_loops: bool
@ -427,9 +427,9 @@ 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.
:param 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.
:param 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`]

22
scripts/modules/bpy_extras/object_utils.py
View file

@ -27,9 +27,9 @@ def add_object_align_init(context, operator):
"""
Return a matrix using the operator settings and view context.
:arg context: The context to use.
:param context: The context to use.
:type context: :class:`bpy.types.Context`
:arg operator: The operator, checked for location and rotation properties.
:param operator: The operator, checked for location and rotation properties.
:type operator: :class:`bpy.types.Operator`
:return: the matrix from the context and settings.
:rtype: :class:`mathutils.Matrix`
@ -87,13 +87,13 @@ def object_data_add(context, obdata, operator=None, name=None):
Add an object using the view context and preference to initialize the
location, rotation and layer.
:arg context: The context to use.
:param context: The context to use.
:type context: :class:`bpy.types.Context`
:arg obdata: Valid object data to used for the new object or None.
:param 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.
:param operator: The operator, checked for location and rotation properties.
:type operator: :class:`bpy.types.Operator`
:arg name: Optional name
:param name: Optional name
:type name: str
:return: the newly created object in the scene.
:rtype: :class:`bpy.types.Object`
@ -238,11 +238,11 @@ def world_to_camera_view(scene, obj, coord):
Takes shift-x/y, lens angle and sensor size into account
as well as perspective/ortho projections.
:arg scene: Scene to use for frame size.
:param scene: Scene to use for frame size.
:type scene: :class:`bpy.types.Scene`
:arg obj: Camera object.
:param obj: Camera object.
:type obj: :class:`bpy.types.Object`
:arg coord: World space location.
:param coord: World space location.
:type coord: :class:`mathutils.Vector`
:return: a vector where X and Y map to the view plane and
Z is the depth on the view axis.
@ -276,9 +276,9 @@ def object_report_if_active_shape_key_is_locked(obj, operator):
If the object has no shape keys, there is nothing to lock, and the function returns False.
:arg obj: Object to check.
:param obj: Object to check.
:type obj: :class:`bpy.types.Object`
:arg operator: Currently running operator to report the error through. Use None to suppress emitting the message.
:param operator: Currently running operator to report the error through. Use None to suppress emitting the message.
:type operator: :class:`bpy.types.Operator`
:return: True if the shape key was locked.
"""

30
scripts/modules/bpy_extras/view3d_utils.py
View file

@ -15,11 +15,11 @@ def region_2d_to_vector_3d(region, rv3d, coord):
Return a direction vector from the viewport at the specific 2d region
coordinate.
:arg region: region of the 3D viewport, typically bpy.context.region.
:param region: region of the 3D viewport, typically bpy.context.region.
:type region: :class:`bpy.types.Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:param 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:
:param coord: 2d coordinates relative to the region:
(event.mouse_region_x, event.mouse_region_y) for example.
:type coord: 2d vector
:return: normalized 3d vector.
@ -62,14 +62,14 @@ def region_2d_to_origin_3d(region, rv3d, coord, *, clamp=None):
To avoid this problem, you can optionally clamp the far clip to a
smaller value based on the data you're operating on.
:arg region: region of the 3D viewport, typically bpy.context.region.
:param region: region of the 3D viewport, typically bpy.context.region.
:type region: :class:`bpy.types.Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:param 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;
:param coord: 2D coordinates relative to the region;
(event.mouse_region_x, event.mouse_region_y) for example.
:type coord: Sequence[float]
:arg clamp: Clamp the maximum far-clip value used.
:param clamp: Clamp the maximum far-clip value used.
(negative value will move the offset away from the view_location)
:type clamp: float | None
:return: The origin of the viewpoint in 3d space.
@ -111,14 +111,14 @@ def region_2d_to_location_3d(region, rv3d, coord, depth_location):
Return a 3d location from the region relative 2d coords, aligned with
*depth_location*.
:arg region: region of the 3D viewport, typically bpy.context.region.
:param region: region of the 3D viewport, typically bpy.context.region.
:type region: :class:`bpy.types.Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:param 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;
:param coord: 2d coordinates relative to the region;
(event.mouse_region_x, event.mouse_region_y) for example.
:type coord: 2d vector
:arg depth_location: the returned vectors depth is aligned with this since
:param depth_location: the returned vectors depth is aligned with this since
there is no defined depth with a 2d region input.
:type depth_location: 3d vector
:return: normalized 3d vector.
@ -155,13 +155,13 @@ def location_3d_to_region_2d(region, rv3d, coord, *, default=None):
"""
Return the *region* relative 2d location of a 3d position.
:arg region: region of the 3D viewport, typically bpy.context.region.
:param region: region of the 3D viewport, typically bpy.context.region.
:type region: :class:`bpy.types.Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:param rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:type rv3d: :class:`bpy.types.RegionView3D`
:arg coord: 3d world-space location.
:param coord: 3d world-space location.
:type coord: 3d vector
:arg default: Return this value if ``coord``
:param default: Return this value if ``coord``
is behind the origin of a perspective view.
:return: 2d location
:rtype: :class:`mathutils.Vector` | Any

6
scripts/modules/gpu_extras/batch.py
View file

@ -11,11 +11,11 @@ def batch_for_shader(shader, type, content, *, indices=None):
"""
Return a batch already configured and compatible with the shader.
:arg shader: shader for which a compatible format will be computed.
:param shader: shader for which a compatible format will be computed.
:type shader: :class:`gpu.types.GPUShader`
:arg type: "'POINTS', 'LINES', 'TRIS' or 'LINES_ADJ'".
:param 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.
:param content: Maps the name of the shader attribute with the data to fill the vertex buffer.
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]]]

18
scripts/modules/gpu_extras/presets.py
View file

@ -12,14 +12,14 @@ def draw_circle_2d(position, color, radius, *, segments=None):
"""
Draw a circle.
:arg position: 2D position where the circle will be drawn.
:param position: 2D position where the circle will be drawn.
:type position: Sequence[float]
:arg color: Color of the circle (RGBA).
:param color: Color of the circle (RGBA).
To use transparency blend must be set to ``ALPHA``, see: :func:`gpu.state.blend_set`.
:type color: Sequence[float]
:arg radius: Radius of the circle.
:param radius: Radius of the circle.
:type radius: float
:arg segments: How many segments will be used to draw the circle.
:param 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 | None
@ -62,16 +62,16 @@ def draw_texture_2d(texture, position, width, height, is_scene_linear_with_rec70
"""
Draw a 2d texture.
:arg texture: GPUTexture to draw (e.g. gpu.texture.from_image(image) for :class:`bpy.types.Image`).
:param texture: GPUTexture to draw (e.g. gpu.texture.from_image(image) for :class:`bpy.types.Image`).
:type texture: :class:`gpu.types.GPUTexture`
:arg position: Position of the lower left corner.
:param position: Position of the lower left corner.
:type position: 2D Vector
:arg width: Width of the image when drawn (not necessarily
:param width: Width of the image when drawn (not necessarily
the original width of the texture).
:type width: float
:arg height: Height of the image when drawn.
:param height: Height of the image when drawn.
:type height: float
:arg is_scene_linear_with_rec709_srgb_target:
:param is_scene_linear_with_rec709_srgb_target:
True if the `texture` is stored in scene linear color space and
the destination frame-buffer uses the Rec.709 sRGB color space
(which is true when drawing textures acquired from :class:`bpy.types.Image` inside a