From 3c4f666509b862e157b38d9fb3eae176e2eccb8d Mon Sep 17 00:00:00 2001 From: rdb Date: Mon, 27 Jul 2020 13:38:47 +0200 Subject: [PATCH] direct: Improvements to API reference, better cross-linking --- direct/src/directbase/DirectStart.py | 2 +- direct/src/showbase/Loader.py | 18 +++++++++--------- direct/src/showbase/Messenger.py | 2 +- direct/src/showbase/ShowBase.py | 11 ++++++----- direct/src/showbase/ShowBaseGlobal.py | 15 ++++++++++----- 5 files changed, 27 insertions(+), 21 deletions(-) diff --git a/direct/src/directbase/DirectStart.py b/direct/src/directbase/DirectStart.py index 8b6b5b9539..ea51d43fc9 100644 --- a/direct/src/directbase/DirectStart.py +++ b/direct/src/directbase/DirectStart.py @@ -4,7 +4,7 @@ opening a graphical window and setting up the scene graph. This example demonstrates its use: import direct.directbase.DirectStart - run() + base.run() While it may be considered useful for quick prototyping in the interactive Python shell, using it in applications is not considered good style. diff --git a/direct/src/showbase/Loader.py b/direct/src/showbase/Loader.py index 80aa5f09e2..fd6424d917 100644 --- a/direct/src/showbase/Loader.py +++ b/direct/src/showbase/Loader.py @@ -24,14 +24,14 @@ class Loader(DirectObject): _loadedPythonFileTypes = False - class Callback: + class _Callback: """Returned by loadModel when used asynchronously. This class is modelled after Future, and can be awaited.""" # This indicates that this class behaves like a Future. _asyncio_future_blocking = False - class ResultAwaiter(object): + class _ResultAwaiter(object): """Reinvents generators because of PEP 479, sigh. See #513.""" __slots__ = 'requestList', 'index' @@ -126,9 +126,9 @@ class Loader(DirectObject): self._asyncio_future_blocking = True if self.gotList: - return self.ResultAwaiter([self]) + return self._ResultAwaiter([self]) else: - return self.ResultAwaiter(self.requestList) + return self._ResultAwaiter(self.requestList) def __aiter__(self): """ This allows using `async for` to iterate asynchronously over @@ -138,7 +138,7 @@ class Loader(DirectObject): requestList = self.requestList assert requestList is not None, "Request was cancelled." - return self.ResultAwaiter(requestList) + return self._ResultAwaiter(requestList) # special methods def __init__(self, base): @@ -308,7 +308,7 @@ class Loader(DirectObject): # requested models have been loaded, we'll invoke the # callback (passing it the models on the parameter list). - cb = Loader.Callback(self, len(modelList), gotList, callback, extraArgs) + cb = Loader._Callback(self, len(modelList), gotList, callback, extraArgs) i = 0 for modelPath in modelList: request = self.loader.makeAsyncRequest(Filename(modelPath), loaderOptions) @@ -476,7 +476,7 @@ class Loader(DirectObject): # requested models have been saved, we'll invoke the # callback (passing it the models on the parameter list). - cb = Loader.Callback(self, len(modelList), gotList, callback, extraArgs) + cb = Loader._Callback(self, len(modelList), gotList, callback, extraArgs) i = 0 for modelPath, node in modelList: request = self.loader.makeAsyncSaveRequest(Filename(modelPath), loaderOptions, node) @@ -1013,7 +1013,7 @@ class Loader(DirectObject): # requested sounds have been loaded, we'll invoke the # callback (passing it the sounds on the parameter list). - cb = Loader.Callback(self, len(soundList), gotList, callback, extraArgs) + cb = Loader._Callback(self, len(soundList), gotList, callback, extraArgs) for i, soundPath in enumerate(soundList): request = AudioLoadRequest(manager, soundPath, positional) request.setDoneEvent(self.hook) @@ -1078,7 +1078,7 @@ class Loader(DirectObject): callback = self.__asyncFlattenDone gotList = True - cb = Loader.Callback(self, len(modelList), gotList, callback, extraArgs) + cb = Loader._Callback(self, len(modelList), gotList, callback, extraArgs) i = 0 for model in modelList: request = ModelFlattenRequest(model.node()) diff --git a/direct/src/showbase/Messenger.py b/direct/src/showbase/Messenger.py index c8d72cb6b4..e4ba5ccda8 100644 --- a/direct/src/showbase/Messenger.py +++ b/direct/src/showbase/Messenger.py @@ -1,5 +1,5 @@ """This defines the Messenger class, which is responsible for most of the -event handling that happens on the Python side. +:ref:`event handling ` that happens on the Python side. """ __all__ = ['Messenger'] diff --git a/direct/src/showbase/ShowBase.py b/direct/src/showbase/ShowBase.py index 984ec8f8f2..1eb66ad94d 100644 --- a/direct/src/showbase/ShowBase.py +++ b/direct/src/showbase/ShowBase.py @@ -1,4 +1,4 @@ -""" This module contains ShowBase, an application framework responsible +""" This module contains `.ShowBase`, an application framework responsible for opening a graphical display, setting up input devices and creating the scene graph. @@ -19,14 +19,15 @@ Built-in global variables Some key variables used in all Panda3D scripts are actually attributes of the ShowBase instance. When creating an instance of this class, it will write many of these variables to the built-in scope of the Python interpreter, so that -they are accessible to any Python module. +they are accessible to any Python module, without the need fors extra imports. While these are handy for prototyping, we do not recommend using them in bigger projects, as it can make the code confusing to read to other Python developers, to whom it may not be obvious where these variables are originating. -Some of these built-in variables are documented further in the -:mod:`~direct.showbase.ShowBaseGlobal` module. +Refer to the :mod:`builtins` page for a listing of the variables written to the +built-in scope. + """ __all__ = ['ShowBase', 'WindowControls'] @@ -2022,7 +2023,7 @@ class ShowBase(DirectObject.DirectObject): def enableAllAudio(self): """ Reenables the SFX and music managers that were active at the time - `disableAllAudio() was called. Meant to be called when the app regains + `disableAllAudio()` was called. Meant to be called when the app regains audio focus. """ self.AppHasAudioFocus = 1 diff --git a/direct/src/showbase/ShowBaseGlobal.py b/direct/src/showbase/ShowBaseGlobal.py index eedffdd1ad..eeef44d4b2 100644 --- a/direct/src/showbase/ShowBaseGlobal.py +++ b/direct/src/showbase/ShowBaseGlobal.py @@ -2,9 +2,14 @@ :class:`~.ShowBase.ShowBase` instance, as an alternative to using the builtin scope. -Note that you cannot directly import `base` from this module since ShowBase -may not have been created yet; instead, ShowBase dynamically adds itself to -this module's scope when instantiated.""" +Many of the variables contained in this module are also automatically written +to the :mod:`builtins` module when ShowBase is instantiated, making them +available to any Python code. Importing them from this module instead can make +it easier to see where these variables are coming from. + +Note that you cannot directly import :data:`~builtins.base` from this module +since ShowBase may not have been created yet; instead, ShowBase dynamically +adds itself to this module's scope when instantiated.""" __all__ = [] @@ -17,8 +22,8 @@ from . import DConfig as config __dev__ = config.GetBool('want-dev', __debug__) -#: The global instance of the :class:`~panda3d.core.VirtualFileSystem`, as -#: obtained using :meth:`panda3d.core.VirtualFileSystem.getGlobalPtr()`. +#: The global instance of the :ref:`virtual-file-system`, as obtained using +#: :meth:`panda3d.core.VirtualFileSystem.getGlobalPtr()`. vfs = VirtualFileSystem.getGlobalPtr() #: The default Panda3D output stream for notifications and logging, as