PyDoc: use Python's type annotation syntax for doc-strings
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
@@ -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))
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user