pymel.core.system.filePathEditor¶

filePathEditor(*args, **kwargs)¶

Maya can reference and use external files, such as textures or other Maya scenes. This command is used to get the information about those file paths and modify them in bulk. By default, only the most frequently used types of files are presented to the user: TextureScene referenceAudioImage planeFor the command to manage more file types, those must be explicitly requested by the caller using the registerTypeflag. This flag tells the command about attributes or nodes that are to reveal their paths when the command is used. Currently, the attributes specified through this flag must have the usedAsFileNameproperty. Supported nodes are referenceand plug-in nodes. For example: brush.flowerImageor referencecan be used as value for this flag. Conversely, the deregisterTypeflag can be used to tell the command to stop handling certain attributes or nodes. Once the set of attributes and nodes to be searched for external files is selected, the command can be used to obtain a list of plugs that contain file names. Additional information can be obtained, such as each file’s name, directory, and report whether the file exists. Additional information about the associated node or plug can also be obtained, such as its name, type and label. Finally, the command can be used to perform various manipulations such as editing the paths, remapping the files or verifying the presence of identically- named files in target directories. See the repath, copyAndRepathand replaceFieldflags for more information. The results of these manipulations can be previewed before they are applied using the previewflag. In query mode, return type is based on queried flag.

Flags:

Long Name / Short Name		Argument Types	Properties
attributeOnly / ao		bool
	Used with listFilesto return the node and attribute name that are using the files.
attributeType / at		unicode
	Query the attribute type for the specified plug.
byType / bt		unicode
	Used with listFilesto query files that are used by the specified node type or attribute type.
copyAndRepath / cr		unicode, unicode
	Copy a source file to the destination path and repath the plug data to the new file. The source file must have the same name as the one in the plug. The command will look for the file at the specified location first. If not found, the command will try to use the original file in the plug. If the file is still not found, nothing is done.
deregisterType / dt		unicode
	Deregister a file type from the list of registered types so the command stops handling it. Unless the temporaryflag is used, the type will be removed from the preferences will not reappear on application restart. When the temporaryflag is specified, the deregistration is only effective for the current session. The deregistration will be rejected if the type has already been unregistered. However, it is valid to deregister permanently (without the temporaryflag) a type after it has been temporarily deregistered.
force / f		bool
	Used with flag repathto repath all files to the new location, including the resolved files. Otherwise, repathwill only deal with the missing files. Used with flag copyAndRepathto overwrite any colliding file at the destination. Otherwise, copyAndRepathwill use the existing file at the destination instead of overwriting it. The default value is off.
listDirectories / ld		unicode
	List all sub directories of the specified directory. Only directories containing at least one file whose type is registered (see registerType) will be listed. If no directory is provided, all directories applicable to the scene will be returned.
listFiles / lf		unicode
	List files in the specified directory. No recursion in subdirectories will be performed.
listRegisteredTypes / lrt		bool
	Query the list of registered attribute types. The registered types include the auto-loaded types from the preference file and the types explicitly registered by the user, both with and without the temporaryflag.
preview / p		bool
	Used with repath, replaceStringor copyAndRepathto preview the result of the operation instead of excuting it. When it is used with repathor replaceString, the command returns the new file path and a status flag indicating whether the new file exists (1) or not (0). The path name and the file status are listed in pairs. When it is used with copyAndRepath, the command returns the files that need copying.
recursive / rc		bool
	Used with flag repathto search the files in the target directory and its subdirectories recursively. If the flag is on, the command will repath the plug to a file that has the same name in the target directory or sub directories. If the flag is off, the command will apply the directory change without verifying that the resulting file exists.
refresh / rf		bool
	Clear and re-collect the file information in the scene. The command does not automatically track file path modifications in the scene. So it is the users responsibility to cause refreshes in order to get up-to-date information.
registerType / rt		unicode
	Register a new file type that the command will handle and recognize from now on. Unless the temporaryflag is used, the registered type is saved in the preferences and reappears on application restart. The new type will be rejected if it collides with an existing type or label. One exception to this is when registering a type without the temporaryflag after the type has been registered with it. This is considered as modifying the persistent/temporary property of the existing type, rather than registering a new type.
relativeNames / rel		bool
	Used with listDirectoriesor listFilesto return the relative path of each directory or file. Paths are relative to the current project folder. If a file or the directory is not under the current project folder, the returned path will still be a full path.
repath / r		unicode
	Replace the directory part of a file path with a specified location. The file name will be preserved.
replaceAll / ra		bool
	Used with flag replaceString, specifies how many times the matched string will be replaced. When the flag is false, only the first matched string will be replaced. Otherwise, all matched strings will be replaced. The default value is false.
replaceField / rfd		unicode
	Used with the replaceStringflag to control the scope of the replacement. Possible values are: pathOnly- only replace strings in the directory part. nameOnly- only replace strings in the file name, without the directory. fullPath- replace strings anywhere in the full name. The default argument is fullPath.
replaceString / rs		unicode, unicode
	Replace the target string with the new string in the file paths. The flag needs two arguments: the first one is the target string and the second one is the new string. See the replaceFieldand replaceAllflags to control how the replacement is performed.
status / s		bool
	Used with listFiles, this will cause the returned list of files to include one status flag per file: 0 if it cannot be resolved and 1 if it can. Used with listDirectories, this will cause the returned list of directories to include one status flag per directory: 0 if it cannot be resolved, 1 if it can and 2 if the resolution is partial. The status will be interleaved with the file/directory names, with the name appearing first. See the example for listFiles. See the withAttributeflag for another way of getting per-file information. When multiple per-entry items appear in the list (e.g.: plug name), the status is always last.
temporary / tmp		bool
	Make the effect of the register/deregisterflag only applicable in the current session. Normally, a type registration/deregistration is permanent and is made persistent via a preference file. When the temporaryflag is specified, the changes will not be saved to the preference file. When the application restarts, any type that has been previously temporarily registered will not appear and any type that was temporarily deregistered will re-appear.
typeLabel / tl		unicode
	Used with registerTypeto set the label name for the new file type. Used with queryto return the type label for the specified attribute type. For default types, the type label is the localized string. For other types, the type label is supplied by user.
unresolved / u		bool
	Used with listFilesto query the unresolved files that are being used in the scene.
withAttribute / wa		bool
	Used with listFilesto return the name of the plug using a given file. For example, if file.jpgis used by the plug node1.fileTextureName, then the returned string will become the pair file.jpg node1.fileTextureName. See the statusflag for another way to get per-file information. Flag can have multiple arguments, passed either as a tuple or a list.

Derived from mel command maya.cmds.filePathEditor

Example:

import pymel.core as pm

#Return the directories of the external files in Maya scene.
#
pm.filePathEditor(query=True, listDirectories="")
#Return the directories of the external files which are
#saved at the target location.
#
pm.filePathEditor(query=True, listDirectories="c:/textures/", status=True)
#Return the files which are saved in the specified directory,
#but not including the files in the sub directories.
#Use "withAttribute" to return the associated plug
#which is using the file.
#Use "status" to return the information that if the files
#exist or not.
#For example, if "stone.jpg" exists and it is used by
#the plug "node1.imageName", then the returned result
#will be an ordered pair: "stone.jpg node1.imageName 1".
#
pm.filePathEditor(query=True, listFiles="c:/textures/", withAttribute=True, status=True)
#Return the label of the specified type.
#For default types, they are localized strings.
#For other types, they are defined by user.
#
pm.filePathEditor(query=True, typeLabel="imagePlane")
# Result: u'' #
#Register and save a new file type and type label.
#Then user can use it next time they open maya
#
pm.filePathEditor(registerType="containerBase.iconName", registerLabel="ContainerIcon")
#Deregister the file type and clean the saved information
#
pm.filePathEditor(deregisterType="containerBase.iconName")
#Register a new file type and type label without saving
#
pm.filePathEditor(registerType="containerBase.iconName", registerLabel="ContainerIcon", temporary=True)
#Deregister the file type but do nothing on the saved information
#
pm.filePathEditor(deregisterType="containerBase.iconName", temporary=True)
#Return all registered types, including default types
#
pm.filePathEditor(query=True, listRegisteredTypes=True)
#Query the attribute type of the plug instance
#
pm.filePathEditor("node1.fileTextureName", query=True, attributeType=True)
#Refresh all file information in the scene
#
pm.filePathEditor(refresh=True)
#Recursively look for the files with the same name in
#the target directory. Repath the plug values to those files.
#Use "force" to edit all given plugs no matter if
#their original paths exist or not.
#Use "recursive" to find files recursively and to make
#sure the files must exist.
#
pm.filePathEditor("node1.fileTextureName", "node2.fileTextureName", repath="e:/textures/",
                                                force=True, recursive=True)
#Preview the result of edit, but not to do the replacement.
#Return the file name and the information that if the new file path
#exists. They are listed in pairs.
#
pm.filePathEditor("node1.fileTextureName", "node2.fileTextureName", repath="e:/textures/", preview=True)
#Replace strings in file path of the plugs.
#Here, only the string "image" in the directory part
#will be replaced by "texture".
#
pm.filePathEditor("node1.fileTextureName", "node2.fileTextureName", replaceField="pathOnly", replaceString=("image", "texture"), replaceAll=True)
#Copy a file from the source to the destination and repath the plug data to the new file.
#Use "force" to overwrite the file at the destination, if it has a name clash.
#
pm.filePathEditor("node1.fileTextureName", "node2.fileTextureName",  copyAndRepath=("e:/textures", "g:/image"), force=True)