File System Service API¶

File System Service Overview¶

Provide access to Device Cloud File System commands that use SCI to get the data from your devices connected to the cloud.

File System Service API Documentation¶

Provide access to Device Cloud file system service API

exception devicecloud.file_system_service.FileSystemServiceException¶: A file system service exception

exception devicecloud.file_system_service.ResponseParseError¶: An Exception when receiving an unexpected SCI response format

class devicecloud.file_system_service.ErrorInfo(errno, message)¶

Represents an error response from the device or the devicecloud

Variables

errno – The error number reported in the response
message – The error message reported in the response

class devicecloud.file_system_service.LsInfo(directories, files)¶

property directories¶: Alias for field number 0

property files¶: Alias for field number 1

class devicecloud.file_system_service.FileInfo(fssapi, device_id, path, last_modified, size, hash, hash_type)¶

Represents a file from a device

This stores the information about a file on the device returned from an ls command. It also provides functionality to get the contents of the represented file and delete it. However, writing to the file is not supported as it would invalidate the other information stored in this object.

Parameters

fssapi (FileSystemServiceAPI) – A FileSystemServiceAPI object to perform device file operations with
device_id – The Device ID of the device this file is on
path – The path to this file on the device
last_modified (int) – The last time the file was modified
size (int) – The size of the file
hash – The files hash
hash_type – The method used to produce the hash

Variables

device_id – The Device ID of the device this file is on
path – The path to this file on the device
last_modified – The last time the file was modified
size – The size of the file
hash – The files hash
hash_type – The method used to produce the hash

get_data()¶

Get the contents of this file

Returns: The contents of this file
Return type: six.binary_type

delete()¶: Delete this file from the device

Note

After deleting the file, this object will no longer contain valid information and further calls to delete or get_data will return ErrorInfo objects

class devicecloud.file_system_service.DirectoryInfo(fssapi, device_id, path, last_modified)¶

Represents a directory from a device

This stores the information about a directory on the device returned from an ls command. It also provides functionality to list the contents of the directory.

Parameters

fssapi (FileSystemServiceAPI) – A FileSystemServiceAPI object to perform device directory operations with
device_id – The Device ID of the device this file is on
path – The path to this file on the device
last_modified (int) – The last time the file was modified

Variables

device_id – The Device ID of the device this file is on
path – The path to this file on the device
last_modified – the last time the file was modified

list_contents()¶

List the contents of this directory

Returns: A LsInfo object that contains directories and files
Return type: LsInfo or ErrorInfo

Here is an example usage:

# let dirinfo be a DirectoryInfo object
ldata = dirinfo.list_contents()
if isinstance(ldata, ErrorInfo):
    # Do some error handling
    logger.warn("Error listing file info: (%s) %s", ldata.errno, ldata.message)
# It's of type LsInfo
else:
    # Look at all the files
    for finfo in ldata.files:
        logger.info("Found file %s of size %s", finfo.path, finfo.size)
    # Look at all the directories
    for dinfo in ldata.directories:
        logger.info("Found directory %s of last modified %s", dinfo.path, dinfo.last_modified)

class devicecloud.file_system_service.FileSystemServiceCommandABC¶

Abstract base class for FileSystemServiceCommands

Variables: command_name – The file_system command name of this command

get_etree()¶: Return an xml.etree.ElementTree.Element that is the root of the command XML for this command

classmethod parse_response(response, **kwargs)¶: Parse the server response for this command type

class devicecloud.file_system_service.LsCommand(path, hash='any')¶

Class representing the ls command to list files on a device

Parameters

path – the path to the device directory to list
hash – the method to generate the file hashes

Variables

command_name – The file_system command name of this command (“ls”)

get_etree()¶

Get the XML representation of this command

Returns: the xml.etree.ElementTree.Element that is the root of the XML of the ls command

classmethod parse_response(response, device_id=None, fssapi=None, **kwargs)¶

Parse the server response for this ls command

This will parse xml of the following form:

<ls hash="hash_type">
  <file path="file_path" last_modified=last_modified_time ... />
  ...
  <dir path="dir_path" last_modified=last_modified_time />
  ...
</ls>

or with an error:

<ls>
    <error ... />
</ls>

Parameters

response (xml.etree.ElementTree.Element) – The XML root of the response for an ls command
device_id – The device id of the device this ls response came from
fssapi – A reference to a FileSystemServiceAPI for use with the FileInfo and DirectoryInfo objects for future commands

Returns

An LsInfo object containing the list of directories and files on the device or an ErrorInfo if the xml contained an error

class devicecloud.file_system_service.GetCommand(path, offset=None, length=None)¶

Class representing the get file command to get the contents of a file on a device

Parameters

path – the path to the file on the device to get the contents of
offset – the point in the file to start reading data from (if None, start at the beginning)
length – the length of data to retrieve (if None, read until the end)

Variables

command_name – The file_system command name of this command (“get_file”)

get_etree()¶

Get the XML representation of this get file command

Returns: the xml.etree.ElementTree.Element that is the root of the XML of the get_file command

classmethod parse_response(response, **kwargs)¶

Parse the server response for this get file command

This will parse xml of the following form:

<get_file>
    <data>
       asdfasdfasdfasdfasf
    </data>
</get_file>

or with an error:

<get_file>
    <error ... />
</get_file>

Parameters: response (xml.etree.ElementTree.Element) – The XML root of the response for a get file command
Returns: a six.binary_type string of the data of a file or an ErrorInfo if the xml contained an error

class devicecloud.file_system_service.PutCommand(path, file_data=None, server_file=None, offset=None, truncate=False)¶

Class representing the put file command to write contents to a file on a device

Parameters

path – The path on the target to the file to write to. If the file already exists it will be overwritten.
file_data – A six.binary_type containing the data to put into the file
server_file – The path to a file on the devicecloud server containing the data to put into the file on the device
offset – Start writing bytes to the file at this position, if None start at the beginning
truncate – Boolean, if True after bytes are done being written end the file their even if previous data exists beyond it. If False, leave any existing data in place.

Variables

command_name – The file_system command name of this command (“put_file”)

get_etree()¶

Get the XML representation of this put file command

Returns: the xml.etree.ElementTree.Element that is the root of the XML of the put file command

classmethod parse_response(response, **kwargs)¶

Parse the server response for this put file command

This will parse xml of the following form:

<put_file />

or with an error:

<put_file>
    <error ... />
</put_file>

Parameters: response (xml.etree.ElementTree.Element) – The XML root of the response for a put file command
Returns: None if everything was ok or an ErrorInfo if the xml contained an error

class devicecloud.file_system_service.DeleteCommand(path)¶

Class representing the delete file command on a device

Parameters: path – The path on the target to the file to delete.
Variables: command_name – The file_system command name of this command (“rm”)

get_etree()¶

Get the XML representation of this delete file command

Returns: the xml.etree.ElementTree.Element that is the root of the XML of the delete file command

classmethod parse_response(response, **kwargs)¶

Parse the server response for this put file command

This will parse xml of the following form:

<rm />

or with an error:

<rm>
    <error ... />
</rm>

Parameters: response (xml.etree.ElementTree.Element) – The XML root of the response for a delete file command
Returns: None if everything was ok or an ErrorInfo if the xml contained an error

class devicecloud.file_system_service.FileSystemServiceAPI(sci_api)¶

Encapsulate the File System Service API

send_command_block(target, command_block)¶

Send an arbitrary file system command block

The primary use for this method is to send multiple file system commands with a single web service request. This can help to avoid throttling.

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
command_block (FileSystemServiceCommandBlock) – The block of commands to execute on the target

Returns

The response will be a dictionary where the keys are device_ids and the values are the parsed responses of each command sent in the order listed in the command response for that device. In practice it seems to be the same order as the commands were sent in, however, Device Cloud documentation does not explicitly state anywhere that is the case so I cannot guarantee it. This does mean that if you send different types of commands the response list will be different types. Please see the commands parse_response functions for what those types will be. (LsCommand.parse_response(), GetCommand.parse_response, PutCommand.parse_response, DeleteCommand.parse_response)

list_files(target, path, hash='any')¶

List all files and directories in the path on the target

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
path – The path on the target to list files and directories from
hash – an optional attribute which indicates a hash over the file contents should be retrieved. Values include none, any, md5, and crc32. any is used to indicate the device should choose its best available hash.

Returns

A dictionary with keys of device ids and values of LsInfo objects containing the files and directories or an ErrorInfo object if there was an error response

Raises

ResponseParseError If the SCI response has unrecognized formatting

Here is an example usage:

# dc is a DeviceCloud instance
fssapi = dc.get_fss_api()

target = AllTarget()
ls_dir = '/root/home/user/important_files/'

ls_data = fssapi.list_files(target, ls_dir)

# Loop over all device results
for device_id, device_data in ls_data.iteritems():
    # Check if it succeeded or was an error
    if isinstance(device_data, ErrorInfo):
        # Do some error handling
        logger.warn("Error listing file info on device %s. errno: %s message:%s",
                    device_id, device_data.errno, device_data.message)

    # It's of type LsInfo
    else:
        # Look at all the files
        for finfo in device_data.files:
            logger.info("Found file %s of size %s on device %s",
                        finfo.path, finfo.size, device_id)
        # Look at all the directories
        for dinfo in device_data.directories:
            logger.info("Found directory %s of last modified %s on device %s",
                        dinfo.path, dinfo.last_modified, device_id)

get_file(target, path, offset=None, length=None)¶

Get the contents of a file on the device

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
path – The path on the target to the file to retrieve
offset – Start retrieving data from this byte position in the file, if None start from the beginning
length – How many bytes to retrieve, if None retrieve until the end of the file

Returns

A dictionary with keys of device ids and values of the bytes of the file (or partial file if offset and/or length are specified) or an ErrorInfo object if there was an error response

Raises

ResponseParseError If the SCI response has unrecognized formatting

put_file(target, path, file_data=None, server_file=None, offset=None, truncate=False)¶

Put data into a file on the device

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
path – The path on the target to the file to write to. If the file already exists it will be overwritten.
file_data – A six.binary_type containing the data to put into the file
server_file – The path to a file on the devicecloud server containing the data to put into the file on the device
offset – Start writing bytes to the file at this position, if None start at the beginning
truncate – Boolean, if True after bytes are done being written end the file their even if previous data exists beyond it. If False, leave any existing data in place.

Returns

A dictionary with keys being device ids and value being None if successful or an ErrorInfo if the operation failed on that device

Raises

FileSystemServiceException if either both file_data and server_file are specified or neither are specified

Raises

ResponseParseError If the SCI response has unrecognized formatting

delete_file(target, path)¶

Delete a file from a device

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
path – The path on the target to the file to delete.

Returns

A dictionary with keys being device ids and value being None if successful or an ErrorInfo if the operation failed on that device

Raises

ResponseParseError If the SCI response has unrecognized formatting

get_modified_items(target, path, last_modified_cutoff)¶

Get all files and directories from a path on the device modified since a given time

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
path – The path on the target to the directory to check for modified files.
last_modified_cutoff (int) – The time (as Unix epoch time) to get files modified since

Returns

A dictionary where the key is a device id and the value is either an ErrorInfo if there was a problem with the operation or a LsInfo with the items modified since the specified date

exists(target, path, path_sep='/')¶

Check if path refers to an existing path on the device

Parameters

target (devicecloud.sci.TargetABC or list of devicecloud.sci.TargetABC instances) – The device(s) to be targeted with this request
path – The path on the target to check for existence.
path_sep – The path separator of the device

Returns

A dictionary where the key is a device id and the value is either an ErrorInfo if there was a problem with the operation or a boolean with the existence status of the path on that device