direct.p3d.Packager

from direct.p3d.Packager import ArgumentError, OutsideOfPackageError, Packager, PackagerError, class_p3d, class_package, class_solo, func_closure, metaclass_def

This module is used to build a “Package”, a collection of files within a Panda3D Multifile, which can be easily be downloaded and/or patched onto a client machine, for the purpose of running a large application.

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 ArgumentError

Bases: PackagerError

class OutsideOfPackageError

Bases: PackagerError

class Packager(platform=None)

Bases: object

class ExcludeFilename(packager, filename, caseSensitive)

Bases: object

__init__(self, packager, filename, caseSensitive)

matches(self, filename)

class HostEntry(url=None, downloadUrl=None, descriptiveName=None, hostDir=None, mirrors=None)

Bases: object

__init__(self, url=None, downloadUrl=None, descriptiveName=None, hostDir=None, mirrors=None)

loadXml(self, xhost, packager)

makeXml(self, packager=None)

Returns a new TiXmlElement.

class PackFile(package, filename, newName=None, deleteTemp=False, explicit=False, compress=None, extract=None, text=None, unprocessed=None, executable=None, dependencyDir=None, platformSpecific=None, required=False)

Bases: object

__init__(self, package, filename, newName=None, deleteTemp=False, explicit=False, compress=None, extract=None, text=None, unprocessed=None, executable=None, dependencyDir=None, platformSpecific=None, required=False)

isExcluded(self, package)

Returns true if this file should be excluded or skipped, false otherwise.

class Package(packageName, packager)

Bases: object

This is the full information on a particular package we are constructing. Don’t confuse it with PackageEntry, above, which contains only the information found in the toplevel contents.xml file.

__init__(self, packageName, packager)

addBamFile(self, file)

addComponent(self, file)

addDcFile(self, file)

Adds a dc file to the archive. A dc file gets its internal comments and parameter names stripped out of the final result automatically. This is as close as we can come to “compiling” a dc file, since all of the remaining symbols are meaningful at runtime.

addDcImports(self, file)

Adds the Python modules named by the indicated dc file.

addEggFile(self, file)

addExtensionModules(self)

Adds the extension modules detected by the freezer to the current list of files.

addFile(self, *args, **kw)

Adds the named file to the package. Returns the file object, or None if it was not added by this call.

addFoundTexture(self, filename)

Adds the newly-discovered texture to the output, if it has not already been included. Returns the new name within the package tree.

addNode(self, node, filename, newName)

Converts the indicated node to a bam stream, and adds the bam file to the multifile under the indicated newName.

addPrcFile(self, file)

Adds a prc file to the archive. Like the dc file, this strips comments and such before adding. It’s also possible to set prcEncryptionKey and/or prcSignCommand to further manipulate prc files during processing.

addPyFile(self, file)

Adds the indicated python file, identified by filename instead of by module name, to the package.

cleanup(self)

close(self)

Writes out the contents of the current package. Returns True if the package was constructed successfully, False if one or more required files or modules are missing.

compressMultifile(self)

Compresses the .mf file into an .mf.pz file.

considerPlatform(self)

excludeFile(self, filename)

Excludes the named file (or glob pattern) from the package.

getFileSpec(self, element, pathname, newName)

Returns an xcomponent or similar element with the file information for the indicated file.

installMultifile(self)

Installs the package, either as a p3d application, or as a true package. Either is implemented with a Multifile.

installSolo(self)

Installs the package as a “solo”, which means we simply copy the one file into the install directory. This is primarily intended for the “coreapi” plugin, which is just a single dll and a jpg file; but it can support other kinds of similar “solo” packages as well.

makeP3dInfo(self)

Makes the p3d_info.xml file that defines the application startup parameters and such.

readDescFile(self)

Reads the existing package.xml file before rewriting it. We need this to preserve the list of patches, and similar historic data, between sessions.

readImportDescFile(self, filename)

Reads the import desc file. Returns True on success, False on failure.

requirePackage(self, package)

Indicates a dependency on the given package. This also implicitly requires all of the package’s requirements as well (though this transitive requirement happens at runtime, not here at build time).

writeDescFile(self)

Makes the package.xml file that describes the package and its contents, for download.

writeImportDescFile(self)

Makes the package.import.xml file that describes the package and its contents, for other packages and applications that may wish to “require” this one.

class PackageEntry

Bases: object

This corresponds to a <package> entry in the contents.xml file.

__init__(self)

fromFile(self, packageName, platform, version, solo, perPlatform, installDir, descFilename, importDescFilename)

getKey(self)

Returns a tuple used for sorting the PackageEntry objects uniquely per package.

loadXml(self, xpackage)

makeXml(self)

Returns a new TiXmlElement.

__init__(self, platform=None)

addAltHost(self, keyword, altHost, origHost=None, downloadUrl=None, descriptiveName=None, hostDir=None, mirrors=None)

Adds an alternate host to any already-known host. This defines an alternate server that may be contacted, if specified on the HTML page, which hosts a different version of the server’s contents. (This is different from a mirror, which hosts an identical version of the server’s contents.)

addFiles(self, filenames, text=None, newName=None, newDir=None, extract=None, executable=None, deleteTemp=False, literal=False, dependencyDir=None, required=False)

Adds the indicated arbitrary files to the current package.

filenames is a list of Filename or string objects, and each may include shell globbing characters.

Each file is placed in the named directory, or the toplevel directory if no directory is specified.

Certain special behavior is invoked based on the filename extension. For instance, .py files may be automatically compiled and stored as Python modules.

If newDir is not None, it specifies the directory in which the file should be placed. In this case, all files matched by the filename expression are placed in the named directory.

If newName is not None, it specifies a new filename. In this case, newDir is ignored, and the filename expression must match only one file.

If newName and newDir are both None, the file is placed in the toplevel directory, regardless of its source directory.

If text is nonempty, it contains the text of the file. In this case, the filename is not read, but the supplied text is used instead.

If extract is true, the file is explicitly extracted at runtime.

If executable is true, the file is marked as an executable filename, for special treatment.

If deleteTemp is true, the file is a temporary file and will be deleted after its contents are copied to the package.

If literal is true, then the file extension will be respected exactly as it appears, and glob characters will not be expanded. If this is false, then .dll or .exe files will be renamed to .dylib and no extension on OSX (or .so on Linux); and glob characters will be expanded.

If required is true, then the file is marked a vital part of the package. The package will not be built if this file somehow cannot be added to the package.

addHost(self, host, downloadUrl=None, descriptiveName=None, hostDir=None, mirrors=None)

Adds a host to the list of known download hosts. This information will be written into any p3d files that reference this host; this can be used to pre-define the possible mirrors for a given host, for instance. Returns the newly-created HostEntry object.

addModule(self, moduleNames, newName=None, filename=None, required=False)

addPosixSearchPath(self, searchPath, varname)

Expands $varname, interpreting as a Posix-style search path, and adds its contents to the indicated DSearchPath.

addWindowsSearchPath(self, searchPath, varname)

Expands $varname, interpreting as a Windows-style search path, and adds its contents to the indicated DSearchPath.

beginPackage(self, packageName, p3dApplication=False, solo=False)

Begins a new package specification. packageName is the basename of the package. Follow this with a number of calls to file() etc., and close the package with endPackage().

buildPatches(self, packages)

Call this after calling close(), to build patches for the indicated packages.

close(self)

Called after reading all of the package def files, this performs any final cleanup appropriate.

do_config(self, **kw)

Called with any number of keyword parameters. For each keyword parameter, sets the corresponding p3d config variable to the given value. This will be written into the p3d_info.xml file at the top of the application, or to the package desc file for a package file.

do_dir(self, dirname, newDir=None, unprocessed=None)

Adds the indicated directory hierarchy to the current package. The directory hierarchy is walked recursively, and all files that match a known extension are added to the package.

newDir specifies the directory name within the package which the contents of the named directory should be installed to. If it is omitted, the contents of the named directory are installed to the root of the package.

If unprocessed is false (the default), bam files are loaded and scanned for textures, and these texture paths within the bam files are manipulated to point to the new paths within the package. If unprocessed is true, this operation is bypassed, and bam files are packed exactly as they are.

do_exclude(self, filename)

Marks the indicated filename as not to be included. The filename may include shell globbing characters, and may or may not include a dirname. (If it does not include a dirname, it refers to any file with the given basename from any directory.)

do_excludeModule(self, *args)

Marks the indicated Python module as not to be included.

do_file(self, *args, **kw)

Adds the indicated file or files to the current package. See addFiles().

do_freeze(self, filename, compileToExe=False)

Freezes all of the current Python code into either an executable (if compileToExe is true) or a dynamic library (if it is false). The resulting compiled binary is added to the current package under the indicated filename. The filename should not include an extension; that will be added.

do_includeExtensions(self, executableExtensions=None, extractExtensions=None, imageExtensions=None, textExtensions=None, uncompressibleExtensions=None, unprocessedExtensions=None, suppressWarningForExtensions=None)

Ensure that dir() will include files with the given extensions. The extensions should not have ‘.’ prefixes.

All except ‘suppressWarningForExtensions’ allow the given kinds of files to be packaged with their respective semantics (read the source).

‘suppressWarningForExtensions’ lists extensions expected to be ignored, so no warnings will be emitted for them.

do_main(self, filename)

Includes the indicated file as __main__ module of the application. Also updates mainModule to point to this module.

do_mainModule(self, moduleName, newName=None, filename=None)

Names the indicated module as the “main” module of the application or exe. In most cases, you will want to use main() instead.

do_makeBundle(self, bundleName, plist, executable=None, resources=None, dependencyDir=None)

Constructs a minimal OSX “bundle” consisting of an executable and a plist file, with optional resource files (such as icons), and adds it to the package under the given name.

do_module(self, *args, **kw)

Adds the indicated Python module(s) to the current package.

do_require(self, *args, **kw)

Indicates a dependency on the named package(s), supplied as a name.

Attempts to install this package will implicitly install the named package also. Files already included in the named package will be omitted from this one when building it.

do_setVer(self, value)

Sets an explicit set_ver number for the package, as a tuple of integers, or as a string of dot-separated integers.

do_setupPanda3D(self, p3dpythonName=None, p3dpythonwName=None)

A special convenience command that adds the minimum startup modules for a panda3d package, intended for developers producing their own custom panda3d for download. Should be called before any other Python modules are named.

do_sign(self, certificate, chain=None, pkey=None, password=None)

Signs the resulting p3d file (or package multifile) with the indicated certificate. If needed, the chain file should contain the list of additional certificate authorities needed to validate the signing certificate. The pkey file should contain the private key.

It is also legal for the certificate file to contain the chain and private key embedded within it.

If the private key is encrypted, the password should be supplied.

endPackage(self)

Closes the current package specification. This actually generates the package file. Returns the finished package, or None if the package failed to close (e.g. missing files).

findPackage(self, packageName, platform=None, version=None, host=None, requires=None)

Searches for the named package from a previous publish operation along the install search path.

If requires is not None, it is a list of Package objects that are already required. The new Package object must be compatible with the existing Packages, or an error is returned. This is also useful for determining the appropriate package version to choose when a version is not specified.

Returns the Package object, or None if the package cannot be located.

loadLdconfigCache(self)

On GNU/Linux, runs ldconfig -p to find out where all the libraries on the system are located. Assumes that the platform has already been set.

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

readContentsFile(self)

Reads the contents.xml file at the beginning of processing.

readPackageDef(self, packageDef, packageNames=None)

Reads the named .pdef file and constructs the named packages, or all packages if packageNames is None. Raises an exception if the pdef file is invalid. Returns the list of packages constructed.

requirePackage(self, package)

Indicates a dependency on the indicated package, supplied as a Package object.

Attempts to install this package will implicitly install the named package also. Files already included in the named package will be omitted from this one.

requirePackagesNamed(self, names, version=None, host=None)

Indicates a dependency on the named package(s), supplied as a name.

Attempts to install this package will implicitly install the named package also. Files already included in the named package will be omitted from this one when building it.

resolveLibrary(self, filename)

Resolves the given shared library filename along the executable path, or by cross-referencing it with the library cache.

setHost(self, host, downloadUrl=None, descriptiveName=None, hostDir=None, mirrors=None)

Specifies the URL that will ultimately host these contents.

setPlatform(self, platform=None)

Sets the platform that this Packager will compute for. On OSX, this can be used to specify the particular architecture we are building; on other platforms, it is probably a mistake to set this.

You should call this before doing anything else with the Packager. It’s even better to pass the platform string to the constructor.

setup(self)

Call this method to initialize the class after filling in some of the values in the constructor.

writeContentsFile(self)

Rewrites the contents.xml file at the end of processing.

class PackagerError

Bases: Exception

class class_p3d

Bases: object

class class_package

Bases: object

class class_solo

Bases: object

class func_closure(name)

Bases: object

This class is used to create a closure on the function name, and also allows the *args, **kw syntax. In Python, the lambda syntax, used with default parameters, is used more often to create a closure (that is, a binding of one or more variables into a callable object), but that syntax doesn’t work with **kw. Fortunately, a class method is also a form of a closure, because it binds self; and this doesn’t have any syntax problems with **kw.

__init__(self, name)

generic_func(self, *args, **kw)

This method is bound to all the functions that might be called from the pdef file. It’s a special function; when it is called, it does nothing but store its name and arguments in the caller’s local scope, where they can be pulled out later.

class metaclass_def(name, bases, dict)

Bases: type

A metaclass is invoked by Python when the class definition is read, for instance to define a child class. By defining a metaclass for class_p3d and class_package, we can get a callback when we encounter “class foo(p3d)” in the pdef file. The callback actually happens after all of the code within the class scope has been parsed first.