DataLakeFileClient class

Definition

A client to interact with the DataLake file, even if the file may not yet exist.

DataLakeFileClient(account_url, file_system_name, file_path, credential=None, **kwargs)
Inheritance
azure.storage.filedatalake._shared.base_client.StorageAccountHostsMixin
azure.storage.filedatalake._path_client.PathClient
DataLakeFileClient

Parameters

account_url
str

The URI to the storage account.

file_system_name
str

The file system for the directory or files.

file_path
str

The whole file path, so that to interact with a specific file. eg. "{directory}/{subdirectory}/{file}"

credential

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the URL already has a SAS token, specifying an explicit credential will take priority.

Examples

Creating the DataLakeServiceClient from connection string.


   from azure.storage.filedatalake import DataLakeFileClient
   DataLakeFileClient.from_connection_string(connection_string, "myfilesystem", "mydirectory", "myfile")

Variables

url
str
The full endpoint URL to the file system, including SAS token if used.
primary_endpoint
str
The full primary endpoint URL.
primary_hostname
str
The hostname of the primary endpoint.

Methods

append_data

Append data to the file.

create_file

Create a new file.

delete_file

Marks the specified file for deletion.

download_file

Downloads a file to the StorageStreamDownloader. The readall() method must be used to read all the content, or readinto() must be used to download the file into a stream.

flush_data

Commit the previous appended data.

from_connection_string

Create DataLakeFileClient from a Connection String.

:return a DataLakeFileClient :rtype ~azure.storage.filedatalake.DataLakeFileClient

get_file_properties

Returns all user-defined metadata, standard HTTP properties, and system properties for the file. It does not return the content of the file.

rename_file

Rename the source file.

upload_data

Upload data to a file.

append_data

Append data to the file.

append_data(data, offset, length=None, **kwargs)

Parameters

data
Required

Content to be appended to file

offset
Required

start position of the data to be appended to.

length
default value: None

Size of the data in bytes.

Returns

dict of the response header

Examples

Append data to the file.


   file_client.append_data(data=file_content[2048:3072], offset=2048, length=1024)

create_file

Create a new file.

create_file(content_settings=None, metadata=None, **kwargs)

Parameters

content_settings
ContentSettings
default value: None

ContentSettings object used to set path properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

Returns

response dict (Etag and last modified).

Examples

Create file.


   file_client = filesystem_client.get_file_client(file_name)
   file_client.create_file()

delete_file

Marks the specified file for deletion.

delete_file(**kwargs)

Returns

None

Examples

Delete file.


   new_client.delete_file()

download_file

Downloads a file to the StorageStreamDownloader. The readall() method must be used to read all the content, or readinto() must be used to download the file into a stream.

download_file(offset=None, length=None, **kwargs)

Parameters

offset
int
default value: None

Start of byte range to use for downloading a section of the file. Must be set if length is provided.

length
int
default value: None

Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.

Returns

A streaming object (StorageStreamDownloader)

Return type

Examples

Return the downloaded data.


   download = file_client.download_file()
   downloaded_bytes = download.readall()

flush_data

Commit the previous appended data.

flush_data(offset, retain_uncommitted_data=False, **kwargs)

Parameters

offset
Required

offset is equal to the length of the file after commit the previous appended data.

retain_uncommitted_data
bool
default value: False

Valid only for flush operations. If "true", uncommitted data is retained after the flush operation completes; otherwise, the uncommitted data is deleted after the flush operation. The default is false. Data at offsets less than the specified position are written to the file when flush succeeds, but this optional parameter allows data after the flush position to be retained for a future flush operation.

Returns

response header in dict

Examples

Commit the previous appended data.


   with open(SOURCE_FILE, "rb") as data:
       file_client = file_system_client.get_file_client("myfile")
       file_client.create_file()
       file_client.append_data(data, 0)
       file_client.flush_data(data.tell())

from_connection_string

Create DataLakeFileClient from a Connection String.

:return a DataLakeFileClient :rtype ~azure.storage.filedatalake.DataLakeFileClient

from_connection_string(conn_str, file_system_name, file_path, credential=None, **kwargs)

Parameters

conn_str
str
Required

A connection string to an Azure Storage account.

file_system_name
str
Required

The name of file system to interact with.

directory_name
str
Required

The name of directory to interact with. The directory is under file system.

file_name
str
Required

The name of file to interact with. The file is under directory.

credential
default value: None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string.

get_file_properties

Returns all user-defined metadata, standard HTTP properties, and system properties for the file. It does not return the content of the file.

get_file_properties(**kwargs)

Return type

FileProperties

Examples

Getting the properties for a file.


   properties = file_client.get_file_properties()

rename_file

Rename the source file.

rename_file(new_name, **kwargs)

Parameters

new_name
str
Required

the new file name the user want to rename to. The value must have the following format: "{filesystem}/{directory}/{subdirectory}/{file}".

Returns

the renamed file client

Return type

DataLakeFileClient

Examples

Rename the source file.


   new_client = file_client.rename_file(file_client.file_system_name + '/' + 'newname')

upload_data

Upload data to a file.

upload_data(data, length=None, overwrite=False, **kwargs)

Parameters

data
Required

Content to be uploaded to file

length
int
default value: None

Size of the data in bytes.

overwrite
bool
default value: False

to overwrite an existing file or not.

Returns

response dict (Etag and last modified).