direct.p3d.AppRunner

from direct.p3d.AppRunner import AppRunner, ArgumentError, ScriptAttributes, dummyAppRunner

This module is intended to be compiled into the Panda3D runtime distributable, to execute a packaged p3d application, but it can also be run directly via the Python interpreter (if the current Panda3D and Python versions match the version expected by the application). See runp3d.py for a command-line tool to invoke this module.

The global AppRunner instance may be imported as follows:

from direct.showbase.AppRunnerGlobal import appRunner

This will be None if Panda was not run from the runtime environment.

Deprecated since version 1.10.0: The p3d packaging system has been replaced with the new setuptools-based system. See the Distributing Panda3D Applications manual section.

Inheritance diagram

class AppRunner

Bases: DirectObject

This class is intended to be compiled into the Panda3D runtime distributable, to execute a packaged p3d application. It also provides some useful runtime services while running in that packaged environment.

It does not usually exist while running Python directly, but you can use dummyAppRunner() to create one at startup for testing or development purposes.

ConfigBasename = 'config.xml'

P3DVCForce = 2

P3DVCNever = 3

P3DVCNone = 0

P3DVCNormal = 1

P3D_CONTENTS_DEFAULT_MAX_AGE = 5

__init__(self)

addPackageInfo(self, name, platform, version, hostUrl, hostDir=None, recurse=False)

Called by the browser for each one of the “required” packages that were preloaded before starting the application. If for some reason the package isn’t already downloaded, this will download it on the spot. Raises OSError on failure.

checkDiskUsage(self)

Checks the total disk space used by all packages, and removes old packages if necessary.

deletePackages(self, packages)

Removes all of the indicated packages from the disk, uninstalling them and deleting all of their files. The packages parameter must be a list of one or more PackageInfo objects, for instance as returned by getHost().getPackage(). Returns the list of packages that were NOT found.

dropObject(self, objectId)

Inform the parent process that we no longer have an interest in the P3D_object corresponding to the indicated objectId. Not intended to be called by user code.

evalScript(self, expression, needsResponse=False)

Evaluates an arbitrary JavaScript expression in the global DOM space. This may be deferred if necessary if needsResponse is False and self.dom has not yet been assigned. If needsResponse is true, this waits for the value and returns it, which means it cannot be deferred.

freshenFile(self, host, fileSpec, localPathname)

Ensures that the localPathname is the most current version of the file defined by fileSpec, as offered by host. If not, it downloads a new version on-the-spot. Returns true on success, false on failure.

getHost(self, hostUrl, hostDir=None)

Returns a new HostInfo object corresponding to the indicated host URL. If we have already seen this URL previously, returns the same object.

This returns the literal referenced host. To return the mapped host, which is the one we should actually download from, see getHostWithAlt().

getHostWithAlt(self, hostUrl)

Returns a suitable HostInfo object for downloading contents from the indicated URL. This is almost always the same thing as getHost(), except in the rare case when we have an alt_host specified in the HTML tokens; in this case, we may actually want to download the contents from a different URL than the one given, for instance to download a version in testing.

getHostWithDir(self, hostDir)

Returns the HostInfo object that corresponds to the indicated on-disk host directory. This would be used when reading a host directory from disk, instead of downloading it from a server. Supply the full path to the host directory, as a Filename. Returns None if the contents.xml in the indicated host directory cannot be read or doesn’t seem consistent.

getPandaScriptObject(self)

Called by the browser to query the Panda instance’s toplevel scripting object, for querying properties in the Panda instance. The attributes on this object are mapped to document.pluginobject.main within the DOM.

getToken(self, tokenName)

Returns the value of the indicated web token as a string, if it was set, or None if it was not.

getTokenBool(self, tokenName)

Returns the value of the indicated web token as a boolean value, if it was set, or None if it was not.

getTokenFloat(self, tokenName)

Returns the value of the indicated web token as a floating-point value value, if it was set, or None if it was not, or not a number.

getTokenInt(self, tokenName)

Returns the value of the indicated web token as an integer value, if it was set, or None if it was not, or not an integer.

initPackedAppEnvironment(self)

This function sets up the Python environment suitably for running a packed app. It should only run once in any given session (and it includes logic to ensure this).

installPackage(self, packageName, version=None, hostUrl=None)

Installs the named package, downloading it first if necessary. Returns true on success, false on failure. This method runs synchronously, and will block until it is finished; see the PackageInstaller class if you want this to happen asynchronously instead.

loadMultifilePrcFiles(self, mf, root)

Loads any prc files in the root of the indicated Multifile, which is presumed to have been mounted already under root.

maxDiskUsage = 2147483648

notify = <direct.directnotify.Notifier.Notifier object>

notifyRequest(self, message)

Delivers a notify request to the browser. This is a “this happened” type notification; it also triggers some JavaScript code execution, if indicated in the HTML tags, and may also trigger some internal automatic actions. (For instance, the plugin takes down the splash window when it sees the onwindowopen notification.

readConfigXml(self)

Reads the config.xml file that may be present in the root directory.

rmtree(self, filename)

This is like shutil.rmtree(), but it can remove read-only files on Windows. It receives a Filename, the root directory to delete.

run(self)

This method calls taskMgr.run(), with an optional exception handler. This is generally the program’s main loop when running in a p3d environment (except on unusual platforms like the iPhone, which have to hand the main loop off to the OS, and don’t use this interface).

scanInstalledPackages(self)

Scans the hosts and packages already installed locally on the system. Returns a list of InstalledHostData objects, each of which contains a list of InstalledPackageData objects.

scriptRequest(self, operation, object, propertyName='', value=None, needsResponse=True)

Issues a new script request to the browser. This queries or modifies one of the browser’s DOM properties. This is a low-level method that user code should not call directly; instead, just operate on the Python wrapper objects that shadow the DOM objects, beginning with appRunner.dom.

operation may be one of [ ‘get_property’, ‘set_property’, ‘call’, ‘evaluate’ ].

object is the browser object to manipulate, or the scope in which to evaluate the expression.

propertyName is the name of the property to manipulate, if relevant (set to None for the default method name).

value is the new value to assign to the property for set_property, or the parameter list for call, or the string expression for evaluate.

If needsResponse is true, this method will block until the return value is received from the browser, and then it returns that value. Otherwise, it returns None immediately, without waiting for the browser to process the request.

sendRequest(self, request, *args)

Delivers a request to the browser via self.requestFunc. This low-level function is not intended to be called directly by user code.

setBrowserScriptObject(self, dom)

Called by the browser to supply the browser’s toplevel DOM object, for controlling the JavaScript and the document in the same page with the Panda3D plugin.

setInstanceInfo(self, rootDir, logDirectory, superMirrorUrl, verifyContents, main, respectPerPlatform)

Called by the browser to set some global information about the instance.

setP3DFilename(self, p3dFilename, tokens, argv, instanceId, interactiveConsole, p3dOffset=0, p3dUrl=None)

Called by the browser to specify the p3d file that contains the application itself, along with the web tokens and/or command-line arguments. Once this method has been called, the application is effectively started.

setRequestFunc(self, func)

This method is called by the browser at startup to supply a function that can be used to deliver requests upstream, to the core API, and thereby to the browser.

setSessionId(self, sessionId)

This message should come in at startup.

setupWindow(self, windowType, x, y, width, height, parent)

Applies the indicated window parameters to the prc settings, for future windows; or applies them directly to the main window if the window has already been opened. This is called by the browser.

stop(self)

This method can be called by JavaScript to stop the application.

writeConfigXml(self)

Rewrites the config.xml to the root directory. This isn’t called automatically; an application may call this after adjusting some parameters (such as self.maxDiskUsage).

class ArgumentError

Bases: AttributeError

class ScriptAttributes

Bases: object

This dummy class serves as the root object for the scripting interface. The Python code can store objects and functions here for direct inspection by the browser’s JavaScript code.

dummyAppRunner(tokens=[], argv=None)

This function creates a dummy global AppRunner object, which is useful for testing running in a packaged environment without actually bothering to package up the application. Call this at the start of your application to enable it.

It places the current working directory under /mf, as if it were mounted from a packed multifile. It doesn’t convert egg files to bam files, of course; and there are other minor differences from running in an actual packaged environment. But it can be a useful first-look sanity check.