PyAPI: make internal modules explicitly "private"

Rename modules in `./scripts/modules/` to use an underscore prefix to
make it clear they aren't intended to be part of public API's. This
also means there is no implication that these modules should be stable,
allowing us to change them based on Blender's internal usage.

The following modules have been marked as private:

- `animsys_refactor`
- `bl_console_utils`
- `bl_i18n_utils`
- `bl_previews_utils`
- `bl_rna_utils`
- `bl_text_utils`
- `bl_ui_utils`
- `bpy_restrict_state`
- `console_python`
- `console_shell`
- `graphviz_export`
- `keyingsets_utils`
- `rna_info`
- `rna_manual_reference`
- `rna_xml`

Note that we could further re-arrange these modules
(under `_bpy_internal` in some cases), this change is mainly to mark
them as private, further changes can be handed on a case-by-case basis.

Ref !147773

doc/python_api/sphinx_changelog_gen.py

@@ -101,7 +101,7 @@ class JSONEncoderAPIDump(json.JSONEncoder):
 
 
 def api_dump(args):
-    import rna_info
+    import _rna_info as rna_info
     import inspect
 
     version, version_key = api_version()

doc/python_api/sphinx_doc_gen.py

@@ -57,7 +57,7 @@ except ImportError:
     print(__doc__)
     sys.exit()
 
-import rna_info  # Blender module.
+import _rna_info as rna_info  # Blender module.
 
 
 def rna_info_BuildRNAInfo_cache():

scripts/addons_core/pose_library/gui.py

@@ -15,7 +15,7 @@ from bpy.types import (
     UILayout,
     UIList,
 )
-from bl_ui_utils.layout import operator_context
+from _bl_ui_utils.layout import operator_context
 
 
 class VIEW3D_MT_pose_modify(Menu):

scripts/addons_core/ui_translate/settings.py

@@ -17,7 +17,7 @@ else:
         BoolProperty,
         StringProperty,
     )
-    from bl_i18n_utils import settings as settings_i18n
+    from _bl_i18n_utils import settings as settings_i18n
 
 
 settings = settings_i18n.I18nSettings()

scripts/addons_core/ui_translate/update_addon.py

@@ -16,8 +16,8 @@ else:
         StringProperty,
     )
     from . import settings
-    from bl_i18n_utils import utils as utils_i18n
+    from _bl_i18n_utils import utils as utils_i18n
-    from bl_i18n_utils import bl_extract_messages
+    from _bl_i18n_utils import bl_extract_messages
 
 from bpy.app.translations import pgettext_rpt as rpt_
 import addon_utils

scripts/addons_core/ui_translate/update_repo.py

@@ -15,8 +15,8 @@ else:
         EnumProperty,
     )
     from . import settings
-    from bl_i18n_utils import utils as utils_i18n
+    from _bl_i18n_utils import utils as utils_i18n
-    from bl_i18n_utils import utils_languages_menu
+    from _bl_i18n_utils import utils_languages_menu
 
 import concurrent.futures
 import io
@@ -85,7 +85,7 @@ class UI_OT_i18n_updatetranslation_work_repo(Operator):
         #       This is a problem because spawned processes do not inherit the whole environment
         #       of the current (Blender-customized) python. In practice, the `bpy` module won't load e.g.
         #       So care must be taken that the callback passed to the executor does not rely on any
-        #       Blender-specific modules etc. This is why it is using a class method from `bl_i18n_utils`
+        #       Blender-specific modules etc. This is why it is using a class method from `_bl_i18n_utils`
         #       module, rather than a local function of this current Blender-only module.
         # FIXME: This can easily deadlock on powerful machine with lots of RAM (128GB) and cores (32)...
         # ~ with concurrent.futures.ProcessPoolExecutor() as exctr:

scripts/addons_core/ui_translate/update_ui.py

@@ -23,7 +23,7 @@ else:
         CollectionProperty,
     )
     from . import settings
-    from bl_i18n_utils import utils as utils_i18n
+    from _bl_i18n_utils import utils as utils_i18n
 
 from bpy.app.translations import pgettext_iface as iface_
 

scripts/modules/_bl_i18n_utils/bl_extract_messages.py

@@ -18,7 +18,7 @@ import glob
 from pathlib import PurePath
 
 # XXX Relative import does not work here when used from Blender...
-from bl_i18n_utils import settings as settings_i18n, utils
+from _bl_i18n_utils import settings as settings_i18n, utils
 
 import bpy
 
@@ -31,7 +31,7 @@ filter_message = ignore_reg.match
 
 def init_spell_check(settings, lang="en_US"):
     try:
-        from bl_i18n_utils import utils_spell_check
+        from _bl_i18n_utils import utils_spell_check
         return utils_spell_check.SpellChecker(settings, lang)
     except Exception as ex:
         print("Failed to import utils_spell_check ({})".format(str(ex)))
@@ -1231,7 +1231,7 @@ def dump_messages(do_messages, do_checks, settings):
     # Get strings specific to translations' menu.
     for lng in settings.LANGUAGES:
         process_msg(
-            msgs, settings.DEFAULT_CONTEXT, lng[1], "Languages’ labels from bl_i18n_utils/settings.py",
+            msgs, settings.DEFAULT_CONTEXT, lng[1], "Languages’ labels from _bl_i18n_utils/settings.py",
             reports, None, settings,
         )
 

scripts/modules/_bl_i18n_utils/utils.py

@@ -22,7 +22,7 @@ import struct
 import tempfile
 import time
 
-from bl_i18n_utils import (
+from _bl_i18n_utils import (
     settings,
     utils_rtl,
 )

scripts/modules/_bl_i18n_utils/utils_languages_menu.py

@@ -56,7 +56,7 @@ def gen_menu_file(stats, settings):
         "# ID must be unique, except for 0 value (marks categories for menu).",
         "# Line starting with a # are comments!",
         "#",
-        "# Automatically generated by bl_i18n_utils/utils_languages_menu.py script.",
+        "# Automatically generated by _bl_i18n_utils/utils_languages_menu.py script.",
         "# Highest ID currently in use: {}".format(highest_uid),
     ]
     for uid_num, label, uid, flag, lvl in langs:

scripts/modules/_console_python.py

@@ -237,7 +237,7 @@ execute.hooks = []
 
 
 def autocomplete(context):
-    from bl_console_utils.autocomplete import intellisense
+    from _bl_console_utils.autocomplete import intellisense
 
     sc = context.space_data
 

scripts/modules/addon_utils.py

@@ -332,7 +332,7 @@ def enable(module_name, *, default_set=False, persistent=False, refresh_handled=
     import os
     import sys
     import importlib
-    from bpy_restrict_state import RestrictBlend
+    from _bpy_restrict_state import RestrictBlend
 
     if handle_error is None:
         def handle_error(ex):

scripts/modules/bl_app_template_utils.py

@@ -35,7 +35,7 @@ _modules = {}
 
 
 def _enable(template_id, *, handle_error=None, ignore_not_found=False):
-    from bpy_restrict_state import RestrictBlend
+    from _bpy_restrict_state import RestrictBlend
 
     if handle_error is None:
         def handle_error(_ex):

scripts/modules/bpy/utils/__init__.py

@@ -321,7 +321,7 @@ def load_scripts(*, reload_scripts=False, refresh_scripts=False, extensions=True
         # Without this, add-on register functions accessing key-map properties can crash, see: #111702.
         _bpy.context.window_manager.keyconfigs.update(keep_properties=True)
 
-    from bpy_restrict_state import RestrictBlend
+    from _bpy_restrict_state import RestrictBlend
 
     with RestrictBlend():
         for base_path in script_paths(use_user=use_user):
@@ -367,7 +367,7 @@ def _on_exit():
 
     # Call `unregister` function on internal startup module.
     # Must only be used as part of Blender 'exit' process.
-    from bpy_restrict_state import RestrictBlend
+    from _bpy_restrict_state import RestrictBlend
     with RestrictBlend():
         for mod_name in reversed(_registered_module_names):
             if (mod := _sys.modules.get(mod_name)) is None:
@@ -1231,7 +1231,7 @@ def _blender_default_map():
     # NOTE(@ideasman42): Avoid importing this as there is no need to keep the lookup table in memory.
     # As this runs when the user accesses the "Online Manual", the overhead loading the file is acceptable.
     # In my tests it's under 1/100th of a second loading from a `pyc`.
-    ref_mod = execfile(_os.path.join(_script_base_dir, "modules", "rna_manual_reference.py"))
+    ref_mod = execfile(_os.path.join(_script_base_dir, "modules", "_rna_manual_reference.py"))
     return (ref_mod.url_manual_prefix, ref_mod.url_manual_mapping)
 
 

scripts/startup/bl_operators/anim.py

@@ -398,7 +398,7 @@ class UpdateAnimatedTransformConstraint(Operator):
     )
 
     def execute(self, context):
-        import animsys_refactor
+        import _animsys_refactor as animsys_refactor
         from math import radians
         import io
 

scripts/startup/bl_operators/console.py

@@ -15,7 +15,7 @@ from bpy.app.translations import contexts as i18n_contexts
 
 def _lang_module_get(sc):
     return __import__(
-        "console_" + sc.language,
+        "_console_" + sc.language,
         # for python 3.3, maybe a bug???
         level=0,
     )

scripts/startup/bl_operators/file.py

@@ -95,7 +95,7 @@ class WM_OT_previews_batch_generate(Operator):
     def execute(self, context):
         import os
         import subprocess
-        from bl_previews_utils import bl_previews_render as preview_render
+        from _bl_previews_utils import bl_previews_render as preview_render
 
         context.window_manager.progress_begin(0, len(self.files))
         context.window_manager.progress_update(0)
@@ -204,7 +204,7 @@ class WM_OT_previews_batch_clear(Operator):
     def execute(self, context):
         import os
         import subprocess
-        from bl_previews_utils import bl_previews_render as preview_render
+        from _bl_previews_utils import bl_previews_render as preview_render
 
         context.window_manager.progress_begin(0, len(self.files))
         context.window_manager.progress_update(0)

scripts/startup/bl_operators/presets.py

@@ -164,7 +164,7 @@ class AddPresetBase:
                 print("Writing Preset: {!r}".format(filepath))
 
                 if is_xml:
-                    import rna_xml
+                    import _rna_xml as rna_xml
                     rna_xml.xml_file_write(context, filepath, preset_menu_class.preset_xml_map)
                 else:
 
@@ -304,7 +304,7 @@ class ExecutePreset(Operator):
                 self.report({'ERROR'}, "Failed to execute the preset: " + repr(ex))
 
         elif ext == ".xml":
-            import rna_xml
+            import _rna_xml as rna_xml
             preset_xml_map = preset_class.preset_xml_map
             preset_xml_secure_types = getattr(preset_class, "preset_xml_secure_types", None)
 
@@ -708,7 +708,7 @@ class SavePresetInterfaceTheme(AddPresetBase, Operator):
     # while redrawing as it may involve remote file-system access.
 
     def execute(self, context):
-        import rna_xml
+        import _rna_xml as rna_xml
         filepath = context.preferences.themes[0].filepath
         if (not filepath) or _is_path_readonly(filepath):
             self.report({'ERROR'}, "Built-in themes cannot be overwritten")

scripts/startup/bl_operators/wm.py

@@ -31,7 +31,7 @@ from bpy.app.translations import (
 
 def _rna_path_prop_search_for_context_impl(context, edit_text, unique_attrs):
     # Use the same logic as auto-completing in the Python console to expand the data-path.
-    from bl_console_utils.autocomplete import intellisense
+    from _bl_console_utils.autocomplete import intellisense
     context_prefix = "context."
     line = context_prefix + edit_text
     cursor = len(line)
@@ -148,7 +148,7 @@ def context_path_validate(context, data_path):
 
 
 def context_path_to_rna_property(context, data_path):
-    from bl_rna_utils.data_path import property_definition_from_data_path
+    from _bl_rna_utils.data_path import property_definition_from_data_path
     rna_prop = property_definition_from_data_path(context, "." + data_path)
     if rna_prop is not None:
         return rna_prop
@@ -167,7 +167,7 @@ def context_path_decompose(data_path):
     # Note that the `.` is removed from the start of the first and second values,
     # this is done because `.attr` isn't convenient to use as an argument,
     # also the convention is not to include this within the data paths or the operator logic for `bpy.ops.wm.*`.
-    from bl_rna_utils.data_path import decompose_data_path
+    from _bl_rna_utils.data_path import decompose_data_path
     path_split = decompose_data_path("." + data_path)
 
     # Find the last property that isn't a function call.
@@ -1342,7 +1342,7 @@ class WM_OT_doc_view_manual(Operator):
             self.report(
                 {'WARNING'},
                 rpt_("No reference available {!r}, "
-                     "Update info in 'rna_manual_reference.py' "
+                     "Update info in '_rna_manual_reference.py' "
                      "or callback to bpy.utils.manual_map()").format(self.doc_id)
             )
             return {'CANCELLED'}

scripts/startup/bl_ui/space_graph.py

@@ -384,7 +384,7 @@ class GRAPH_MT_key_density(Menu):
     bl_label = "Density"
 
     def draw(self, _context):
-        from bl_ui_utils.layout import operator_context
+        from _bl_ui_utils.layout import operator_context
         layout = self.layout
         layout.operator("graph.decimate", text="Decimate (Ratio)").mode = 'RATIO'
         # Using the modal operation doesn't make sense for this variant

scripts/startup/bl_ui/space_sequencer.py

@@ -1075,7 +1075,7 @@ class SEQUENCER_MT_strip(Menu):
     bl_label = "Strip"
 
     def draw(self, context):
-        from bl_ui_utils.layout import operator_context
+        from _bl_ui_utils.layout import operator_context
 
         layout = self.layout
         st = context.space_data

scripts/startup/bl_ui/space_topbar.py

@@ -553,7 +553,7 @@ class TOPBAR_MT_window(Menu):
 
     def draw(self, context):
         import sys
-        from bl_ui_utils.layout import operator_context
+        from _bl_ui_utils.layout import operator_context
 
         layout = self.layout
 

scripts/startup/bl_ui/space_view3d.py

@@ -3212,7 +3212,7 @@ class VIEW3D_MT_object_parent(Menu):
     bl_translation_context = i18n_contexts.operator_default
 
     def draw(self, _context):
-        from bl_ui_utils.layout import operator_context
+        from _bl_ui_utils.layout import operator_context
 
         layout = self.layout
 

scripts/startup/keyingsets_builtins.py

@@ -15,7 +15,7 @@ are supported.
 """
 
 import bpy
-import keyingsets_utils
+import _keyingsets_utils as keyingsets_utils
 from bpy.types import KeyingSetInfo
 
 ###############################

source/blender/editors/space_text/text_ops.cc

@@ -3985,11 +3985,11 @@ static bool text_jump_to_file_at_point_external(bContext *C,
   err_info.reports = reports;
   err_info.report_prefix = "External editor";
 
-  const char *expr_imports[] = {"bl_text_utils", "bl_text_utils.external_editor", "os", nullptr};
+  const char *expr_imports[] = {"_bl_text_utils", "_bl_text_utils.external_editor", "os", nullptr};
   std::string expr;
   {
     std::stringstream expr_stream;
-    expr_stream << "bl_text_utils.external_editor.open_external_editor(os.fsdecode(b'";
+    expr_stream << "_bl_text_utils.external_editor.open_external_editor(os.fsdecode(b'";
     for (const char *ch = filepath; *ch; ch++) {
       expr_stream << "\\x" << std::hex << int(*ch);
     }

source/blender/makesrna/rna_cleanup/rna_cleaner.py

@@ -11,7 +11,7 @@ Typical line in the input file (elements in [] are optional).
 [comment *] ToolSettings.snap_align_rotation -> use_snap_align_rotation:    boolean    [Align description]
 
 Geterate output format from blender run this:
- ./blender.bin --background --python ./scripts/modules/rna_info.py 2> source/blender/makesrna/rna_cleanup/out.txt
+ ./blender.bin --background --python ./scripts/modules/_rna_info.py 2> source/blender/makesrna/rna_cleanup/out.txt
 """
 
 

tests/python/bl_load_py_modules.py

@@ -18,8 +18,8 @@ import os
 # The trailing components of the path are used instead of the module name.
 # Both script files & directories are supported which prevents searching inside the directory.
 EXCLUDE_MODULE_PATHS = {
-    "bl_i18n_utils",
+    "_bl_i18n_utils",
-    "bl_previews_utils",
+    "_bl_previews_utils",
     "cycles",
 
     # These tests which run stand-alone and aren't imported as modules.

tests/python/bl_rna_manual_reference.py

@@ -17,7 +17,7 @@ VERBOSE = False
 
 
 def test_data():
-    import rna_manual_reference
+    import _rna_manual_reference as rna_manual_reference
 
     assert isinstance(rna_manual_reference.url_manual_mapping, tuple)
     for i, value in enumerate(rna_manual_reference.url_manual_mapping):
@@ -37,7 +37,7 @@ def lookup_rna_url(rna_id, visit_indices):
     A local version of ``WM_OT_doc_view_manual._lookup_rna_url``
     that tracks which matches are found.
     """
-    import rna_manual_reference
+    import _rna_manual_reference as rna_manual_reference
     from fnmatch import fnmatchcase
     rna_id = rna_id.lower()
     for i, (pattern, url_suffix) in enumerate(rna_manual_reference.url_manual_mapping):
@@ -51,7 +51,7 @@ def lookup_rna_url(rna_id, visit_indices):
 def test_lookup_coverage():
 
     def rna_ids():
-        import rna_info
+        import _rna_info as rna_info
         struct = rna_info.BuildRNAInfo()[0]
         for struct_id, v in sorted(struct.items()):
             props = [(prop.identifier, prop) for prop in v.properties]
@@ -96,7 +96,7 @@ def test_lookup_coverage():
     print("---------------------------------------")
     print("Unused RNA Patterns Known to the Manual")
 
-    import rna_manual_reference
+    import _rna_manual_reference as rna_manual_reference
     for i, (pattern, url_suffix) in enumerate(rna_manual_reference.url_manual_mapping):
         if i not in visit_indices:
             print(pattern, url_suffix)
@@ -118,7 +118,7 @@ def test_language_coverage():
 def test_urls():
     import os
     import sys
-    import rna_manual_reference
+    import _rna_manual_reference as rna_manual_reference
 
     import urllib.error
     from urllib.request import urlopen

tests/python/rna_info_dump.py

@@ -97,7 +97,7 @@ def api_dump(use_properties=True, use_functions=True):
         data.insert(0, "# * properties *")
         return data
 
-    import rna_info
+    import _rna_info as rna_info
     struct = rna_info.BuildRNAInfo()[0]
     data = []
 

tools/check_source/check_descriptions.py

@@ -92,7 +92,7 @@ DUPLICATE_IGNORE = {
 
 
 def check_duplicates():
-    import rna_info
+    import _rna_info as rna_info
 
     DUPLICATE_IGNORE_FOUND = set()
     DUPLICATE_ACCEPT_FOUND = set()

tools/check_source/check_spelling_config.py

@@ -907,7 +907,7 @@ dict_ignore_hyphenated_suffix = {
 }
 
 files_ignore = {
-    "scripts/modules/bl_i18n_utils/utils_spell_check.py",  # UI spelling, doesn't always match code spelling.
+    "scripts/modules/_bl_i18n_utils/utils_spell_check.py",  # UI spelling, doesn't always match code spelling.
     "tools/utils/git_data_canonical_authors.py",  # Too many names which aren't in the dictionary.
     "tools/utils_doc/rna_manual_reference_updater.py",  # Contains language ID references.
 

tools/utils/autopep8_clean_config.py

@@ -40,6 +40,6 @@ PATHS_EXCLUDE: set[str] = set(
         "tools/svn_rev_map/sha1_to_rev.py",
         "tools/svn_rev_map/rev_to_sha1.py",
         "tools/svn_rev_map/rev_to_sha1.py",
-        "scripts/modules/rna_manual_reference.py",
+        "scripts/modules/_rna_manual_reference.py",
     )
 )

tools/utils_doc/rna_manual_reference_updater.py

@@ -142,7 +142,7 @@ def main():
     parser.add_argument(
         "--output",
         dest="output",
-        default=os.path.join(BASE_DIR, "scripts", "modules", "rna_manual_reference.py"),
+        default=os.path.join(BASE_DIR, "scripts", "modules", "_rna_manual_reference.py"),
         required=False,
         help="path to output including filename and extentsion",
         metavar="FILE")

tools/utils_maintenance/autopep8_format_paths.py

@@ -46,7 +46,7 @@ extensions = (
 )
 
 ignore_files = {
-    "scripts/modules/rna_manual_reference.py",  # Large generated file, don't format.
+    "scripts/modules/_rna_manual_reference.py",  # Large generated file, don't format.
     "tools/svn_rev_map/rev_to_sha1.py",
     "tools/svn_rev_map/sha1_to_rev.py",
 }

tools/utils_maintenance/blender_update_themes.py

@@ -15,7 +15,7 @@ import os
 
 
 def update(filepath):
-    import rna_xml
+    import _rna_xml as rna_xml
     context = bpy.context
 
     print("Updating theme: {!r}".format(filepath))