fcsxml.FCSVRClient

class fcsxml.FCSVRClient(entityType='asset', entityID=0, id=0, entityPath='', configParser='')

Our FCSVRClient object, it is our interface for reading and manipulating data from Final Cut Server via the fcsvr_client executable installed at /Library/Application Support/Final Cut Server/Final Cut Server.bundle/Contents/MacOS/fcsvr_client

Parameters:

• entityType (str) – The Type of entity: ‘asset’ or ‘project’ (production)
• entityID (int) – The unique numeric FCS id of this object
• entityPath (str) – The FCS entity path for this object (i.e. ‘/asset/10’)
• configParser (ConfigParser.SafeConfigParser or str) – An optional ConfigParser object to configure default behavior. Alternatively this can be a file system path to a configuration file to load

Note

If an entityPath value is provided, it will override values for entityType and id

If upon creation the object is provided enough information to uniquely resolve the FCS object (either via specifying entityType,id, or entityPath), the object will init via FCSVRClient.initWithAssetID().

Thus, this:

>>> myFCSObj = fcsxml.FCSVRClient()
>>> myFCSObj.initWithProductionID(10)
True

Is equivalent to:

>>> myFCSObj = fcsxml.FCSVRClient(entityPath='/project/10')

Is equivalent to:

>>> myFCSObj = fcsxml.FCSVRClient(entityType='project',entityID=10)

Other notable ways to init an FCSVRClientObject:

>>> myFCSObj = fcsxml.FCSVRClient().initWithAssetTitle(title='my great file')
>>> myFCSObj = fcsxml.FCSVRClient().initWithProductionTitle(title='My Production')
>>> myFCSObj = fcsxml.FCSVRClient().initWithAssetFromFSPath(FSPath='/FinalCutServer/Library/my great file.mov')
>>> myFCSObj = fcsxml.FCSVRClient().initWithAssetFromFSPath(FSPath='/FinalCutServer/Library/my great file.mov')

addAssetToProduction(asset='', assetID='', assetPath='', productionPath='', productionID='')

Adds an asset to production.

Warning

This function is depricated as of 07/22/10, use the fcsxml.FCSVRClient.addMemberToProduction() class!

addMemberToProduction(member='', memberPath='', production='', productionPath='', moveLink=False)

Adds entity to the specified production. Accepts either a FCSVRClient object (member) or a FCS entity path ‘/asset/10’ (memberPath) in addition to a FCSVRClient object with entityType ‘production’, or a production path ‘/project/10’. If the local entity is either the member to be added, or is a production, then you can omit that information.

Parameters:

• member (fcsxml.FCSVRClient) – Provide an FCSVRClient object to add. (optional)
• memberPath (str) – Provide an FCS entity Path (optional)
• production (fcsxml.FCSVRClient) – Provide an FCSVRClient object representative of the production to which the member will be added. (optional)
• productionPath (str) – Provide an FCS entity Path representative of the production to which the member will be added. (optional)
• moveLink – Specify whether this is an additional link for the asset, or if it will cancel out any other memberships.
• moveLink – bool

Raises :

FCSError

For instance, if we are a loaded production I can call:

>>> myObj = fcsxml.FCSVRClient(entityType='project',entityID=10)
>>> myObj.addMemberToProduction(memberPath='/asset/20')

Which will add asset with ID 20 to our own membership. Likewise, we will accomplish the exact same thing if we call:

>>> myObj = fcsxml.FCSVRClient(entityType='asset',entityID=20)
>>> myObj.addMemberToProduction(productionPath='/project/10')

Lastly, if we call:

>>> myObj = fcsxml.FCSVRClient(entityType='project',entityID=10)
>>> myObj.addMemberToProduction(productionPath='/project/12')

We will add ourself (a production) as a child production to /project/12.

New in version .96b.

analyze(force=False, FCP=False, recurseProductions=False)

This method will force FCS to analyze the loaded entity.

Parameters:

• force (bool) – Specify whether we call fcsvr_client with the –force option
• FCP (bool) – Specify whether we call fcsvr_client with the –fcp option
• recurseProductions (bool) – Specify whether we recurse production membership when analyzing assets.

appendField(field)

This method will add a new FCSXMLField to the objects field definition list. This function will raise an FCSDuplicate exception if a field object with same name already exists.

Parameters:field (fcsxml.FCSXMLField) – Provide an FCSXMLField object loaded with field name and value Returns:(bool) True or False Raises :fcsxml.FCSDuplicateError, RuntimeError

appendValueForField(fieldName, value, useTimestamp=False)

Appends a value to field, concatenating with the current field value.

Parameters:

• fieldName (str) – Provide the field name
• value (id) – Provide the value to append.
• useTimeStamp (bool) – If set to true, we will prepend a timestamp to the data to be appended.

Raises :

fcsxml.FCSFieldNotFoundError

archive(deviceID='', deviceDict='', recurseProductions=False)

This method archives the loaded entity. If this is a production, then we will archive all assets which are members of the production. If recurseProductions is true, then we will archive it’s members as well. Either deviceID or a deviceDict must be provided to specify the destination archive device.

Parameters:

• deviceID (int) – Specify the device ID to archive to.
• deviceDict (dict) – Specify the device dict profile to archive to (optional)
• recurseProductions (bool) – Specify whether to recurse productions for archiving (assuming the calling entity is a production).

Raises :

FCSAssetOfflineError, FCSError,

assetWithField(field, mdSet='', matchType='exact')

Returns a new FCSVRClient object matching the provided fcsxml.FCSXMLObject.

Parameters:

• field (fcsxml.FCSXMLObject) – Provide the field to match
• mdSet (str) – An optional parameter that can be provided to limit search results to a specific FCS metadata set. This should be the FCS metadata set id (i.e. “pa_asset_media”)
• matchType (str) – An optional parameter to specify the search behavior. Currently two matchType’s are supported: ‘exact’ (default), and ‘substring’

Returns:

(fcsxml.FCSVRClient) – Asset entity matching provided parameters.

Raises :

FCSEntityNotFoundError

New in version 1.0b.

assetWithTitle(title, mdSet='', matchType='exact')

Returns a new FCSVRClient object matching the provided title.

Parameters:

• title (str) – Provide the asset title to search for
• mdSet (str) – An optional parameter that can be provided to limit search results to a specific FCS metadata set. This should be the FCS metadata set id (i.e. “pa_asset_media”)
• matchType (str) – An optional parameter to specify the search behavior. Currently two matchType’s are supported: ‘exact’ (default), and ‘substring’

Returns:

(fcsxml.FCSVRClient) – Asset entity matching provided parameters.

Raises :

FCSEntityNotFoundError

New in version .96b.

assetsFromProduction(productionID='', productionTitle='', recurse=False, mdSet='')

Function which returns a list of associated FCSVRClient asset objects. If recurse is set to true, we will return assets for subproductions as well. If mdSet is provided, we will return only assets which have the provided metadataset. This function utilizes fcsxml.FCSVRClient.productionMemberAddresses()

Parameters:

• productionID (int) – Specify the production ID to query (optional)
• productionTitle (str) – Specify a production title to query (optional)
• recurse (bool) – Specify whether we will recurse through sub-productions
• mdSet (str) – Specify a metadata set by which to filter results

Raises :

FCSValidationError, FCSProductionLoadError

Returns:

(list) – A list of FCSVRClient entries.

assetsFromProject(projectID='', mdSet='')

Function which returns a list of associated FCSVRClient asset objects for the provided Final Cut Pro project file. This project file is referenced via the file’s Final Cut Server asset id. If mdSet is provided, we will return only assets which match the provided metadata set. This function utilizes fcsxml.FCSVRClient.projectElementAddresses()

Parameters:

• projectID (int) – Specify the FCS Asset ID for the project file
• mdSet (str) – Specify a FCS metadata set to filter by (i.e. ‘pa_asset_media’)

Returns:

(list) – A list of qualifying FCSVRClient asset objects.

createAssetFromFSPath(path, deviceName='', deviceID='', mdSet='', relPath='', overwriteExistingFiles='ignore', setMD=True, backgroundAnalyze=True)

This function takes a filesystem path and will create an asset from the file. Can be passed a deviceName or deviceID, metadata set, and an optional relative path to be uploaded. An option overwriteExistingFiles determines behavior if a file already exists, options are ‘ignore’,’iterate’, and ‘overwrite’.

Parameters:

• path (str) – Specify the absolute path to the asset to be added.
• deviceName (str) – Specify the deviceName to which the asset will be added (optional - deviceID MUST be specified if deviceName is not)
• deviceID – Specify the deviceID to which the asset will be added (optional - deviceName MUST be specified if deviceID is not)
• mdSet (str) – Specify the FCS metadata set to use for the new asset.
• relPath (str) – Specify the path, relative to the root of the specified device
• overWriteExistingFiles (str) – Specify the behavior to undertake in the event that a file already exists at the specified path. Options include ‘ignore’, ‘iterate’, or ‘overwrite’
• setMD (bool) – Specify whether we commit loaded field data to the new object.
• backgroundAnalyze (bool) – Specify whether the new asset will be analyzed by FCS in the background (default True)

Raises :

FCSVRClientFileError,FCSEntityNotFoundError,FCSEntityNotFoundError, FCSValidationError, IOError

createPosterFrame(newPosterFramePath, assetID='', deviceName='', deviceID='', mdSet='asset_graphic')

This function will generate a new poster frame for the provided asset based upon the provided path to the new file. This posterframe file is not directly used as the poster frame, rather FCS will generate a new posterframe using it’s standard defined parameters, and will then use this generated file as the asset’s new poster frame. This is accomplished by creating a new FCS asset for the poster frame file, allowing FCS to create the posterframe link to the asset, getting the new asset’s posterframe path, linking it to our asset, and then deleting the new poster frame asset. If you wish to use a file for a posterframe as-is, use fcsxml.FCSVRClient.replacePosterFrame()

Parameters:

• newPosterFramePath (str) – Provide the full path to the image file from which the new poster frame will be generated
• assetID (int) – Provide the asset ID for the asset which will recieve the new thumbnail
• deviceName (str) – Specify the device name to which the temporary thumbnail asset will be copied
• deviceID (int) – Specify the device id to which the temporary thumbnail asset will be copied
• mdSet (str) – Provide the metadata set that will be used for the temporary thumbnail asset. The default value is ‘asset_graphic’

createProduction(title='', mdSet='', parentProjectAddress='', setMD=False)

This method will create a new production based upon loaded and provided values.

Parameters:

• title (str) – Provide the new production’s title.
• mdSet (str) – specify the metadata set for the new production. If none is provided, we will use the default.
• parentProjectAddress (str) – If desired, provide an entity path (i.e. /project/10) to link this production to.
• setMD (bool) – Flag to determine if stored fields will be written to the newly created production.

Returns:

(fcsxml.FCSVRClient) – The new FCSVRClient object loaded with the provided information; if our current object was a ‘project’ type entity, values will be loaded locally as well.

Raises :

FCSProductionLoadError

createThumbnail(newThumbnailPath, assetID='', deviceName='', deviceID='', mdSet='asset_graphic')

This function will generate a new thumbnail for the provided asset based upon the provided path to the new thumbnail file. This thumbnail file is not directly used as the thumbnail, rather FCS will generate a new thumbnail using it’s standard defined parameters, and will then use this generated file as the asset’s new thumbnail. This is accomplished by creating a new FCS asset for the thumbnail file, allowing FCS to create the thumbnail link to the asset, getting the new asset’s thumbnail path, linking it to our asset, and then deleting the new thumbnail asset. If you wish to use a file for a thumbnail as-is, use fcsxml.FCSVRClient.replaceThumbnail()

Parameters:

• newThumbnailPath (str) – Provide the full path to the image file from which the new thumbnail will be generated
• assetID (int) – Provide the asset ID for the asset which will recieve the new thumbnail
• deviceName (str) – Specify the device name to which the temporary thumbnail asset will be copied
• deviceID (int) – Specify the device id to which the temporary thumbnail asset will be copied
• mdSet (str) – Provide the metadata set that will be used for the temporary thumbnail asset. The default value is ‘asset_graphic’

dataTypeForDBFieldName(dbname)

Returns a dataType value for field with dbname (we use FCSXMLField Object and self.dbDataTypeForDBFieldName for this).

Parameters:dbname (str) – The FCS DB Field name Returns:(str) – The data type for the requested db field name.

dataTypeForField(field)

This method returns the datatype for the passed field name.

Parameters:field (fcsxml.FCSXMLField, str) – Provide the FCSXMLField or field name of the field to query. Raises :fcsxml.FCSFieldNotFoundError Returns:(str) Datatype for the specified field

dbDataTypeForDBFieldName(dbname)

Returns a FCS DB dataType value for field with dbname (we use FCSXMLField Object and self.dbDataTypeForDBFieldName for this).

Parameters:dbname (str) – The FCS DB Field name Returns:(str) – The FCS DB data type for the requested db field name

dbDataTypeForField(field)

This function returns the FCS DB datatype for the requested field. Please see the table outlined in fcsxml.FCSVRClient.setDataType() for information about available FCS DB Data types

Parameters:field (fcsxml.FCSXMLField, str) – Provide the FCSXMLField or field name of the field to query. Raises :fcsxml.FCSFieldNotFoundError Returns:(str) FCS DB Datatype for the specified field

dbFieldNameForFieldName(fieldName)

Returns a FCS DB field name for a standard field name (fcsvr_client field name from FCS Read XML field name.

Parameters:fieldName (str) – The field name to be queried. Returns:(str) – The fcsvr_client compatable DB field name.

delete()

Deletes the loaded entity.

Raises :FCSValidationError, FCSVRClientPermissionDenied

deviceWithID(id)

This method will return a dict entry containing pertinent device information for the device matching the provided device id. See the table listed in fcsxml.FCSVRClient.getDevicesMap() for a list of values contained in this dict.

Parameters:id (int) – Provide the device id Returns:(dict) – A dictionary populated with information detailing the requested device. Raises :fcsxml.FCSEntityNotFoundError

deviceWithName(id)

This method will return a dict entry containing pertinent device information for the device matching the provided device name. See the table listed in fcsxml.FCSVRClient.getDevicesMap() for a list of values contained in this dict.

Parameters:id (str) – Provide the device name Returns:(dict) – A dictionary populated with information detailing the requested device. Raises :fcsxml.FCSEntityNotFoundError, fcsxml.FCSError

deviceWithPath(path)

This method will return a dict entry containing pertinent device information for the device configured at the provided POSIX filesystem path. See the table listed in fcsxml.FCSVRClient.getDevicesMap() for a list of values contained in this dict.

Parameters:path – Provide a full file system path Returns:(dict) – A dictionary populated with information detailing the requested device. Raises :fcsxml.FCSEntityNotFoundError, fcsxml.FCSError

fcsvr_client_create(address='', entityType='', parentAddress='', parentLinkType='')

This is a wrapper around fcsvr_client, if there are fields set in self.fields, it will import with generate XML to a temp file and pass it during creation

Warning

This is currently a placeholder function and is not implemented.

fcsvr_client_createasset(fcsPath, mdSet='pa_asset_media', backgroundAnalyze=False, projAddress='', setMD=True)

This is the createasset wrapper around fcsvr_client. If there are fields set in self.fields, It will output XML to a temp file and then call fcsvr_client to create the entity. If self.entityType is ‘asset’, then we load from fcsvr_client and return our self, if our entityType is not asset, we clone ourself and return a new FCSVRClient object with entityType ‘asset’

fcsvr_client_error(errorString='', cmdString='')

This method interprets an fcsvr_client error string and will throw the appropriate exception, it should be called if fcsvr_client returns a non-0 exit code.

Parameters:

• errorString (str) – Provide the text string returned by fcsvr_client
• cmdString (str) – Provide the command string resulting in the error (optional)

Raises :

FCSVRClientError, FCSVRClientFileError, FCSVROfflineError, FCSDuplicateError

Returns:

This function will always raise an exception from the above list

fcsvr_client_make_link(linkType, parentPath='', childPath='', moveLink=False)

This is a wrapper function around fcsvr_client make_link. See the table defined in fcsxml.FCSVRClient.getValueForLinkType() for more information about linkTypes.

Parameters:

• linkType (int) – Specify the type of link to create
• parentPath (str) – Specify the FCS entity path representing the parent (i.e. ‘/project/22’)
• childPath (str) – Specify the FCS entity path representing the child (i.e. ‘/asset/10’)
• moveLink (bool) – Specify whether we are creating a new link (::False::) or moving the existing link (::true::)

Raises :

FCSValidationError, FCSError, FCSVRClientPermissionDenied

fieldNameForDBFieldName(dbname)

Returns a field name for a dbname (FCS Read XML field name from FCSVR_CLIENT field name.

Parameters:dbname (str) – The FCS DB name for the field to be queried. Returns:(str) – The field name.

fieldWithName(fieldName)

This method returns the fcsxml.FCSXMLField object for the passed field name.

Parameters:fieldName (str) – Provide the name of the field to query. Raises :fcsxml.FCSFieldNotFoundError Returns:(fcsxml.FCSXMLField) – The stored field object for the specified field

flushCaches()

This function will flush any cached data: currently this is limited to any cached XML data returned from fcsvr_client.

generateSearchXML(fields, matchType='exact')

Generates an XML file for use by fcsvr_client search –xmlcrit, should be past a list of FCSXMLFields (with their appropriate values set). Returns an absolute path to the XML file.

Parameters:

• fields (list) – Provide a list of FCSXMLField objects with populated values to use for searching.
• matchType (str) – An optional parameter to specify the search behavior. Currently two matchType’s are supported: ‘exact’ (default), and ‘substring’

Returns:

(str) POSIX Filesystem Path to temporary XML file.

New in version .96b.

generateTempXMLFile()

This file generates a temporary XML file constructed based upon our stored fields, used by various metadata activities utilized by fcsvr_client.

Returns:(str) – File path to the temporary file. Raises :FCSValidationError, IOError

getArchiveFilePath(deviceName='')

This method will return the filesystem path for the asset as it exists on the specified device.

Parameters:deviceName (str) – Specify the name of the device to query. Returns:(str) – The full POSIX path to the entity as it exists when archived.

New in version 1.0b.

getChildLinksXML(id='', type='')

This method returns an xml.dom.minidom object of child links data utilizing fcsvr_client This is the sister object to fcsxml.FCSVRClient.getParentLinksXML()

Parameters:

• id (int) – Specify the entity id to determine child links for
• type (str) – Specify the entity type

Raises :

FCSError,FCSValidationError

Returns:

(xml.dom.minidom) – An XML DOM object base upon fcsvr_client XML output

getDevicesMap(useCache=True)

This method will load device information from FCS, returning a multi dimensional dictionary containing information about all configured FCS devices. The top level of the dictionary is keyed by device id. Each device entry in this dictionary will be populated with the following key+value entries:

Key	Description
DEVICE_NAME	(str) The name of the device
DEV_ROOT_PATH	(str) The path to the device on the file system.
FSPATH	(str) An alias for DEV_ROOT_PATH
DEVICE_TYPE	(str) The type of device (filesystem vs contentbase)
DEVICE_ID	(int) The device’s unique ID
DESC_DEVICE_ADDRESS	(str) The device’s FCS entity path (i.e. /dev/2)
DEV_ARCHIVE	(bool) True if the device is an archive device.

Returns:(dict) – A dict object populated with the above information for all devices configured in FCS.

getFCSPathForLinkType(linkType, id='', xmlDOM='')

Returns a Final Cut server relative path for linked assets

getFCSPathFromFSPath(FSPath)

Resolves a FCS Relative device path (‘/dev/4/myfile.mov’)

from a filesystem POSIX path (‘/Users/Shared/FCSStore/Library/myfile.mov’)

Parameters:FSPath (str) – Specify the file system path to convert Returns:(str) – A Final Cut Server relative path

getFCSUID()

Determine the UID of the running FCS User, this is stored in /Library/Preferences/com.apple.FinalCutServer.settings.plist

Returns:(int) – The user ID of the Final Cut Server runtime user.

getFSPathForLinkType(linkType, id='', xmlDOM='')

Returns a filesystem path from a linked asset

getFSPathFromArchivePath(archiveFilePath)

Resolves a POSIX ‘online’ Path from a POSIX archive PATH i.e.: /MyArchiveDevicePath/4/myfile.mov -> /LibraryDevicePath/myfile.mov

Parameters:archiveFilePath (str) – Specify the assets file system path as it exists on the archive device. Raises :FCSObjectLoadError Returns:(str) – The full path to the asset when it is in an online state

getFSPathFromFCSPath(fcsPath)

Resolves a POSIX file system path (‘/Users/Shared/FCSStore/Library/myfile.mov’) from a FCS Relative device path (‘/dev/4/myfile.mov’)

Parameters:fcsPath (str) – Specify the file system path to convert Returns:(str) – A POSIX file system path

getFilePath(id='')

Returns the file path to the primary representation for the loaded asset or the provided asset id.

Parameters:id (int) – Specify the asset ID to query Returns:(str) – The full POSIX path to the entity’s primary representation

getFilePathForEditProxy(id='', xmlDOM='')

Returns filesystem path to the associated thumbnail.

Parameters:

• id (int) – Specify the asset ID to query
• xmlDOM (xml.dom.minidom) – Specify a XML DOM object to evaluate

Raises :

RuntimeError, fcsxml.FCSVRClient.FCSVRClientError

Returns:

(str) – The absolute path to the file.

getFilePathForPosterFrame(id='', xmlDOM='')

Returns filesystem path to the associated poster frame

Parameters:

• id (int) – Specify the asset ID to query
• xmlDOM (xml.dom.minidom) – Specify a XML DOM object to evaluate

Raises :

RuntimeError, fcsxml.FCSVRClient.FCSVRClientError

Returns:

(str) – The absolute path to the file.

getFilePathForProxy(id='', xmlDOM='')

Returns filesystem path to the associated proxy file.

Parameters:

• id (int) – Specify the asset ID to query
• xmlDOM (xml.dom.minidom) – Specify a XML DOM object to evaluate

Raises :

RuntimeError, fcsxml.FCSVRClient.FCSVRClientError

Returns:

(str) – The absolute path to the file.

getFilePathForThumbnail(id='', xmlDOM='')

Returns the filesystem thumbnail path for asset given ID, loads from fcsvr_client.

Parameters:

• id (int) – Specify the asset ID to query
• xmlDOM (xml.dom.minidom) – Specify a XML DOM object to evaluate

Raises :

RuntimeError, fcsxml.FCSVRClient.FCSVRClientError

Returns:

(str) – The absolute path to the file.

getParentLinksXML(id='', type='')

‘Returns an xml.dom.minidom object of parent link data utilizing fcsvr_client. This is the sister object to fcsxml.FCSVRClient.getChildLinksXML()

Parameters:

• id (int) – Specify the entity id to determine parent links for
• type (str) – Specify the entity type

Raises :

FCSError,FCSValidationError

Returns:

(xml.dom.minidom) – An XML DOM object base upon fcsvr_client XML output

getThumbnailPath(assetID='', xmlDOM='')

This function will return a file system path for the given asset.

Warning

This method has been DEPRICATED: use fcsxml.FCSVRClient.getFilePathForThumbnail()

getValueForLinkType(value, linkType, xmlDOM='', id='', type='', origin='parent')

This method is used to interpret results from an fcsvr_client get_link operation. It will parse the provided information and returns the value of <value> node with id of value and LINK_TYPE of linkType. If xmlDOM is provided, we will search it, otherwise we will generate our own xmlDOM for the search using provided or stored values of entityID and entityType. Argument ‘origin’ can be provided to denote whether we are fetching parent (fcsxml.FCSVRClient.getParentLinksXML()) or child (fcsxml.FCSVRClient.getChildLinksXML()) links.

Parameters:

• value (str) – The name of the XML node who’s value we should return
• linkType (int) – The FCS Link type to return
• xmlDOM – Provide the XML DOM object to evaluate (optional - if none is provided we will utilize fcsxml.FCSVRClient.getParentLinksXML() or fcsxml.FCSVRClient.getChildLinksXML())
• id (int) – Specify the entity id for which to analyze links
• type (str) – Specify the entity type for which to analyze links
• origin (str) – Specify the origin of the link (‘parent’ or ‘child’)

Returns:

(str) – The value of the provided nodename and linktype

Appropriate asset link types:

linkType	Description	Origin
1	Asset’s Parent Production	Child
2	Asset’s Primary Representation	Parent
4	Asset’s Proxy	Parent
5	Asset’s Thumbnail	Parent
6	Asset’s Poster frame	Parent
16	Production Nesting	Parent

initFieldWithDBName(dbname)

Returns a FCSXMLField object from a dbname. Uses fcsvr_client to retrieve all the necessary parameters for the field. This method differs from loadFieldWithDBName() in that this method will only init a generic FCSXMLField object, the resulting object will NOT be cached as a member of this object, and no value will be populated for the field (as it is not associated to any particular entity).

Parameters:dbname (str) – The field name to be queried. Returns:(fcsxml.FCSXMLField) – The associated FCSXMLField object.

initFieldWithFieldName(fieldName)

Returns a FCSXMLField object from a provided fieldName. Uses fcsvr_client to retrieve all the necessary parameters for the field. This method differs from loadFieldWithName() in that this method will only init a generic FCSXMLField object, the resulting object will NOT be cached as a member of this object, and no value will be populated for the field (as it is not associated to any particular entity).

Parameters:fieldName (str) – The field name to be queried. Returns:(fcsxml.FCSXMLField) – The associated FCSXMLField object

initWithAssetFromFCSPath(FCSPath)

Inits the local instance with an asset based on the provided FCS device relative path (i.e. ‘/dev/4/myfile.mov’) .

Parameters:FCSPath (str) – Specify the Final Cut Server relative path to init with Raises :FCSEntityNotFoundError, FCSObjectLoadError, RuntimeError

initWithAssetFromFSPath(FSPath)

Inits the local instance with an asset based on the provided file system path.

Parameters:FSPath (str) – Specify the file system path for the asset to init with Raises :FCSEntityNotFoundError, FCSObjectLoadError, RuntimeError

initWithAssetFromField(field, matchType='exact')

Inits the local instance with an asset which has the provided field. A second parameter, matchType, can be provided which will dictate the type of search that is used. Possible options are ‘exact’ and ‘substring’

Parameters:

• field (fcsxml.FCSXMLField) – Specify the field to search with
• matchType (str) – Specify the search criteria, possible values are ‘exact’ and ‘substring’

Raises :

FCSEntityNotFoundError, FCSObjectLoadError, RuntimeError

Example usage:

>>> import fcsxml
>>> myObj = fcsxml.FCSVRClient(configParser='/usr/local/etc/transmogrifier.conf')
>>> myObj.initWithAssetField(field=fcsxml.FCSXMLField(name='Title',dbname='CUST_TITLE',value='photo 1'))
>>> myObj.entityPath()
  /asset/43

initWithAssetID(assetID)

Inits the local instance with an asset based on the provided asset id.

Parameters:assetID (int) – Specify the production id to init with Raises :FCSEntityNotFoundError, FCSObjectLoadError, RuntimeError

initWithAssetTitle(title, matchType='exact')

Inits the local instance with an asset which has the provided asset title. A second parameter, matchType, can be provided which will dictate the type of search that is used. Possible options are ‘exact’ and ‘substring’

Parameters:

• title (str) – Specify the asset title to init with
• matchType (str) – Specify the search criteria, possible values are ‘exact’ and ‘substring’

Raises :

FCSEntityNotFoundError, FCSObjectLoadError, RuntimeError

initWithProductionID(productionID)

Inits the local instance with a production based on the provided production id.

Parameters:productionID (int) – Specify the production id to init with

initWithProductionTitle(title, matchType='exact')

Inits the local instance with a production based on the provided title. A second parameter, matchType, can be provided which will dictate the type of search that is used. Possible options are ‘exact’ and ‘substring’

Parameters:

• title (str) – Specify the production title to init with
• matchType (str) – Specify the search criteria, possible values are ‘exact’ and ‘substring’

loadConfiguration(parser=None, filePath=None)

This method will load internal parameters as specified in the provided ConfigParser.SafeConfigParser object, or via the configuration file referenced via the filePath parameter.

Parameters:

• parser (ConfigParser.SafeConfigParser) – A configuration object.
• filePath (str) – An absolute path to a configuration file.

Note

If you subclass, you should call this parent function. If we raise a RuntimeError Exception, you should abort or perform your own exhaustive sanity checks

loadField(field)

Function which loads the specified field. If the field is not defined for our entity in Final Cut Server, we will still return a FCSXMLField object with all members populated, short of the value field.

Parameters:field (fcsxml.FCSXMLField) – Provide the field object to load Raises :fcsxml.FCSFieldNotFoundError, fcsxml.FCSVRClientError, fcsxml.FCSError,fcsxml.FCSVRClientError Returns:(fcsxml.FCSXMLField) – The loaded field object

loadFieldWithName(name='', dbname='')

Function which loads the specified field. If the field is not defined for our entity in Final Cut Server, we will still return a FCSXMLField object with all members populated, short of the value field.

Parameters:

• name (str) – Provide the field name to load
• dbname (str) – Provide the field db name to load

Raises :

fcsxml.FCSFieldNotFoundError,fcsxml.FCSVRClientError,RuntimeError, fcsxml.FCSError

Returns:

(fcsxml.FCSXMLField) – The loaded field object

loadFromFCSXMLObject(fcsXMLObject)

This method will load our object based upon values stored in the provided fcsxml.FCSXMLObject

Parameters:fcsXMLObject (fcsxml.FCSXMLObject) – Provide the FCSXMLObject to load from

old_initAssetFromFCSPath(FCSPath)

loads our object based upon a FCS path

parentProductions(id='', entityType='asset')

Function which returns a list of associated project addresses: [“/project/11”] representative of all productions that an entity is a member of, based on passed integer value entity. The ID can be omitted if we are a loaded asset or project.

Parameters:

• id (int) – Specify the entity ID for which to resolve parent links
• entityType (str) – Specify the entityType

Raises :

fcsxml.FCSValidationError

Returns:

(list) – A list containing all parent entity addresses

productionAssetAddresses(productionID='', productionTitle='', recurse=False)

Function which returns asset addresses ‘/asset/12’ from a production. If recurse is set to true, we will recurse through any nested productions and collate their addresses.

Parameters:

• productionID (int) – Specify the production ID to query (optional)
• productionTitle (str) – Specify a production title to query (optional)
• recurse (bool) – Specify whether we will recurse through sub-productions

Raises :

FCSValidationError, FCSProductionLoadError

productionMemberAddresses(productionID='', productionTitle='', recurse=False, _processedMemberAddresses=None)

Function which returns all entity addresses [‘/asset/12’,’/project/10’] from a production. If recurse is set to true, we will recurse through any nested productions and collate their memberships. The _processedMemberAddresses parameter is a list of previously processed production addresses to prevent infinite recursion scenarios

Parameters:

• productionID (int) – Specify the production ID to query (optional)
• productionTitle (str) – Specify a production title to query (optional)
• recurse (bool) – Specify whether we will recurse through sub-productions
• _processedMemberAddresses (list) – Specify a list of previously processed production addresses (used internally to prevent infinite recursion)

Raises :

FCSValidationError, FCSProductionLoadError, FCSEntityNotFoundError

productionWithTitle(title, mdSet='', matchType='exact')

Returns a new FCSVRClient production/project object matching the provided production title.

Parameters:

• title (str) – Provide the production title to search for
• mdSet (str) – An optional parameter that can be provided to limit search results to a specific FCS metadata set. This should be the FCS metadata set id (i.e. “pa_production_show”)
• matchType (str) – An optional parameter to specify the search behavior. Currently two matchType’s are supported: ‘exact’ (default), and ‘substring’

Returns:

(fcsxml.FCSVRClient) – Asset entity matching provided parameters.

Raises :

FCSEntityNotFoundError

projectElementAddresses(id='', addressType='asset')

Function which returns a list of element addresses associated to an FCP project file. An optional argument, addressType, can be provided. When set to ‘asset’, we return /asset/ addresses for any linked elements. if set to ‘element’, we return /element/ addresses for all linked alements.

Parameters:

• id (int) – Specify the FCS Asset ID for the project file (optional)
• addressType (str) – Specify the link type to return (‘asset’ or ‘element’)

Returns:

(list) – A list of qualifying entity addresses.

quoteString(path)

This method returns a quoted string acceptable for use by fcsvr_client. This is similar to a URL encode, but FCS has some special needs outside of this as well.

Parameters:path (str) – Specify the path to quote. Returns:(str) – The encoded string.

removeFieldWithName(fieldName)

Remove FCSXMLField object registered with passed field name.

Parameters:fieldName (str or fcsxml.FCSXMLField) – Provide the field name (or an FCSXMLField object) to be removed from the current object’s field list. Raises :fcsxml.FCSFieldNotFoundError, RuntimeError

removeMemberFromProduction(member='', memberPath='', production='', productionPath='', tempProductionMDSet='')

Removes a member from a production. Accepts either an FCSVRClient object (member) or a FCS entity path ‘/asset/10’ (memberPath) in a addition to a FCSVRClient object with project entityType (production) or a production path ‘/project/10’ (productionPath). If calling instance is either a production or an asset, you can omit the appropriate arguments. We also accept tempProductionMDSet: which is the md set used to create a temporary production. (We do this because FCS can’t explicitely delete an existing link, but it CAN relocate links).

Parameters:

• member (fcsxml.FCSVRClient) – Provide an FCSVRClient object to remove. (optional)
• memberPath (str) – Provide an FCS entity Path (optional)
• production (fcsxml.FCSVRClient) – Provide an FCSVRClient object representative of the production who’s member will be removed. (optional)
• productionPath (str) – Provide an FCS entity Path representative of the production who’s member will be removed. (optional)
• tempProductionMDSet – Provide a metadata set type that will be used to create a temporary production.

Raises :

FCSError, FCSValidationError

For instance, if we have a loaded asset, we can remove it from our production as follows:

>>> myObj = fcsxml.FCSVRClient(entityType='asset',entityID=20)
>>> myObj.removeMemberFromProduction(productionPath='/project/10')

Or, alternatively, if we are a loaded production, we can remove an asset as follows (accomplishing the exact same thing as above):

>>> myObj = fcsxml.FCSVRClient(entityType='project',entityID=10)
>>> myObj.removeMemberFromProduction(memberPath='/asset/20')

replacePosterFrame(newPosterFramePath, assetID='')

Method which will replace the poster frame file for the specified/stored assetID with file provided at newPosterFramePath. Unlike fcsxml.FCSVRClient.createPosterFrame(), this function will use the provided file directly as the new posterFrame by simply replacing the existing posterframe file on disk.

Parameters:

• newPosterFramePath (str) – Specify the full path to the new thumbnail image
• assetID (int) – Specify the asset id for the asset which will recieve the new thumbnail image

replaceThumbnail(newThumbnailPath, assetID='')

Method which will replace the thumbnail file for the specified/stored assetID with file provided at newThumbnailPath. Unlike fcsxml.FCSVRClient.createThumbnail(), this function will use the provided file directly as the new thumbnail by simply replacing the existing thumbnail file on disk.

Parameters:

• newThumbnailPath (str) – Specify the full path to the new thumbnail image
• assetID (int) – Specify the asset id for the asset which will recieve the new thumbnail image

restore(recurseProductions=False)

Restores the loaded entity. If this is a production, then we will restore all assets which are members of the production. If recurseProductions is true, then we will restore it’s members as well.

Parameters:recurseProductions (bool) – Specify whether we recursively restore assets for the provided production. Raises :FCSError, FCSVRClientPermissionDenied, FCSVRClientFileError

setField(field)

This method register’s the provided FCSXMLField object, replacing existing field object with same name if it should exist.

Parameters:field (fcsxml.FCSXMLField) – Provide an FCSXMLField object loaded with field name and value Returns:(bool) True or False

setMD()

If we have a valid entityType and ID, we will attempt to run an fcsvr_client –setmd operation. This is performed by writing a temporary XML file (utilizing fcsxml.FCSVRClient.generateTempXMLFile() and reading it in with fcsvr_client –xml setmd

Raises :FCSVRClientPermissionDenied,FCSValidationError,IOError

unquoteString(path)

This method will reverse any string encoding performed by it’s sister method fcsxml.FCSVRClient.quoteString()

Parameters:path (str) – Specify the path to quote. Returns:(str) – The unencoded string.

valueForDBField(dbFieldName)

This method returns the value for the passed FCS database field. (i.e. “pa_cust_md_my_field”)

Parameters:dbFieldName (str) – Provide the FCS database name of the field to query. Raises :fcsxml.FCSFieldNotFoundError Returns:(str) Value for the specified field

valueForField(fieldName)

This method returns the stored value for the passed database field name. (i.e. “My Field”)

param fieldName:  Provide the name of the field to query. type fieldName:str raises:fcsxml.FCSFieldNotFoundError returns:(str) Value for the specified field

xmlOut(filePath)

Output our XML to the specified file, this will be a fcsvr_client compatable XML file (which is not compatable with FCS ReadXML responses)

Parameters:filePath (str) – Specify the filePath for which to output XML Returns:(bool)

Example Code

The following section illustrates some example uses of FCSVRClient.

Import the fcsxml module and instantiate an asset at entity path /asset/22:

>>> import fcsxml
>>> myFCSVRAsset = fcsxml.FCSVRClient(id=22,entityType='asset')

Tell the asset to restore:

>>> myFCSVRAsset.restore()

Set the value of field Export to FM to True:

## Generate our field object.
>>> myField = fcsxml.FCSXMLField(name='Export to FM',value=True,dataType='bool')

## Associate the new field object to our asset
>>> myFCSVRAsset.setField(myField)

## Commit the field to FCS
>>> myFCSVRAsset.setMD()

Instantiate a production object for entity path /project/12:

>>> myFCSVRProd = fcsxml.FCSVRCLient(id=12,entityType='project')

Add our previously created asset as a member to our production:

>>> myFCSVRProd.addMemberToProduction(member=myFCSVRAsset)

Archive all members of our production (as well as nested productions):

>>> myFCSVRProd.archive(recurseProductions=True)

Mass modify assets in our production (as well as nested productions):

>>> myAssets = myFCSVRProd.assetsFromProduction(recurse=True)
>>> myField = fcsxml.FCSXMLField(name="Owner",value="Monica")
>>> for asset in myAssets:
>>>   asset.setField(myField)
>>>   asset.setMD()

Please refer to the fcsxml.FCSVRClient API reference for more usage information.