pymel.core.system.filePathEditor

filePathEditor(*args, **kwargs)

Maya can reference and use external files, such as texture files and other referenced Maya scenes. Therefore, this command is used to get the information about the file paths and modify them in bulk. Due to the fact that user may want to see the most frequently-used types of files, file path editor will only list four default types when user use it at the first time. Except from the four default types of files( the files which are used on texture, reference, audio and image plane ), user need to use the flag “registerType” to tell the command that which type of attribute ( must be “usedAsFileName” ) or of node ( only “reference” and plugin node ) the command should take care of as well, such as “brush.flowerImage” or “reference”. User can also use the flag ‘deregisterType’ to tell the command that they do not want it to manage the specified type any more. After user register the attributes, they can use the command to query the files and the plugs which own them in the scene( or they can register nothing, only the default types of files will be listed then ). The command can list the information of each file, including its directory, the file name and if the file exists. The command can also list the information of the associated node/plug, including its name, the type name and the type label. Besides, user can use the command to edit each file path. User can use different flags to do different kinds of remapping, such as look for a file with the same name in the target directory or copy the file to a directory and remap the path to it(please see flags “repath”, “copyAndRepath” and “replaceField”). All the results of these operations can be previewed, user can know the final state of each path through the returned values(please see flag “preview”). In query mode, return type is based on queried flag.

Flags:

Long name (short name)		Argument Types	Properties
attributeType (at)		unicode
	Query the attribute type of the specified plug.
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 original file of the plug. The command will look for the file from the source location first. If no appropriate file found, the command will try to use the original file of the plug. If the file is still absent, nothing will happen then.
deregisterType (dt)		unicode
	Deregister file type from the registered list to indicate that the command do not need to manage that kind of files and remove the saved types in the preference file to disable auto-loading type. To deregister a type temporarily, please use the flag “temporary”. Then the type will still be auto-loaded. The flag cannot remove an unregistered type. However, if a type has been deregistered temporarily, user can deregister it without “temporary” to remove the saved type in the preference file.
force (f)		bool
	Used with flag “repath” to repath all files to the new location, including the resolved files. Otherwise, “repath” will only deal with the missing files. Used with flag “copyAndRepath” to overwrite the clash file at the destination. Otherwise, “copyAndRepath” will use the existing file at the destination instead of overwriting it. The default value is off.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.
listDirectories (ld)		unicode
	List all sub directories of the specified directory, the sub directories must have one or more files and the types of these files have been registered. If no specified directory is provided, all appropriate directories in the scene will be returned.
listFiles (lf)		unicode
	List files in the specified directory. No files in the sub directory will be returned.
listRegisteredTypes (lrt)		bool
	Query registered attribute types. The registered types include the auto-loaded types from the preference file and the manually registered types from user(both with and without “temporary”).
preview (p)		bool
	Used with “repath”, “replaceString” or “copyAndRepath” to preview the result of the operation instead of excuting it. When it is used with “repath” or “replaceString”, the command returns the new file path and the information that if the new file exists or not. The path name and the file status are listed in pairs. When it is used with “copyAndRepath”, the command returns the files which need copying.
recursive (rc)		bool
	Used with flag “repath” to search the files in the target directory and its sub directories recursively. If the flag is on, the command will repath the plug to the file which has the same name in the target directory or the sub directories. If the flag is off, the command will only change the file path and replace the directory part of the file with the new target directory no matter if the new file exists or not.
refresh (rf)		bool
	Clear and re-collect the file information in the scene. Due to the fact that the command cannot know if user has modified some file paths in the scene, user need to use this flag to ask the command to update the file information.
registerType (rt)		unicode
	Register a new file type to make the command be able to handle this kind of files and save the type in the preference file to auto-load the type when user restart Maya and file path editor. The flag cannot deal with an occupied type or an occupied label which means the type has been registered/saved and it is using another label or the label has been registered/saved and it is used by another type. However, if a type and its label is registered temporarily (please see the flag “temporary”), user can register them again without “temporary” to save it in the preference file. Then the type will be auto-loaded as well.
relativeNames (rel)		bool
	Used with “listDirectories” or “listFiles” to return the relative path of each directory or each file. If the file or the directory is not in 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 reserved.
replaceAll (ra)		bool
	Used with flag “replaceString”, specifies how many times the matched string can 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 of the flag is false.
replaceField (rfd)		unicode
	Used with flag “replaceString” to control the scope of replacement. Only the matched string in the associated part can be replaced: “pathOnly” - only the strings in the directory part “nameOnly” - only the strings in the file name(no directory) “fullPath” - any strings in the full name The default argument of the flag 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. Used with “replaceField” or “replaceAll” together to control how the replacement need to be performed.
status (s)		bool
	Used with “listFiles” to query the existence of one or more files under a directory. The returned status will follow its associated file in the returned list. (please see the sample of “listFiles”)
temporary (tmp)		bool
	Used to make the flag “register”/”deregister” not to save any changes in the preference file. The saved types in preference file will be auto-loaded when user restart Maya. If this flag is on, “register”/”deregister” will only affect the loaded types in Maya. And the temporary types will not be loaded next time user open Maya.
typeLabel (tl)		unicode
	Used with ‘registerType’ to set the label name for the new file type. Used with ‘query’ to return the type label of the specified attribute type. For default types, the type label is the localized string. For other types, the type label is given by user.
withAttribute (wa)		bool
	Used with “listFiles” to return the plug which is using the file. For example, if “file.jpg” is used by the plug “node1.fileTextureName”, then the returned string will become an ordered pair : “file.jpg node1.fileTextureName”.

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)