File

A generic file class representing a file with a specified format. Provides both async and sync interfaces for file operations. All methods without _sync suffix are async.

Attributes

Attribute	Type	Description
path	str	The path to the file (can be local or remote)
name	Optional[str] = null	Optional name for the file (defaults to basename of path)
format	str = ""	The format type of the file, used for generic type representation.
hash	Optional[str] = null	The hash value used for cache key computation and data integrity verification.
hash_method	Optional[HashMethod] = null	The method or accumulator used to compute the file hash during read or write operations.

---

Constructor

Signature

def File(
    path: str,
    name: Optional[str] = None,
    format: str = "",
    hash: Optional[str] = None,
    hash_method: Optional[HashMethod] = None
)

Parameters

Name	Type	Description
path	str	The path to the file (can be local or remote).
name	Optional[str] = None	Optional name for the file; defaults to the basename of the path.
format	str = ""	The format type of the file.
hash	Optional[str] = None	Optional hash value for the file.
hash_method	Optional[HashMethod] = None	The method used to compute the file hash.

---

Methods

---

pre_init()

@classmethod
def pre_init(
    data: dict
)

Internal: Pydantic validator to set default name from path. Not intended for direct use.

Parameters

Name	Type	Description
data	dict	The raw initialization data used to populate model fields

---

lazy_uploader()

@classmethod
def lazy_uploader(
    lazy_uploader: Callable | None
) - > Callable | None

Gets or sets the internal lazy uploader function used to defer local file uploads to remote storage.

Parameters

Name	Type	Description
lazy_uploader	`Callable	None`

Returns

Type	Description
`Callable	None`

---

schema_match()

@classmethod
def schema_match(
    incoming: dict
) - > boolean

Internal: Check if incoming schema matches File schema. Not intended for direct use.

Parameters

Name	Type	Description
incoming	dict	The schema dictionary to compare against the File schema

Returns

Type	Description
boolean	True if the incoming dictionary schema matches the File model schema

---

new_remote()

@classmethod
def new_remote(
    file_name: Optional[str],
    hash_method: Optional[HashMethod | str]
) - > [File](file.md?sid=flyte_io__file_file)[T]

Create a new File reference for a remote file that will be written to.

Parameters

Name	Type	Description
file_name	Optional[str]	Optional string specifying a remote file name. If not set, a generated file name will be returned.
hash_method	`Optional[HashMethod	str]`

Returns

Type	Description
[File](file.md?sid=flyte_io__file_file)[T]	A new File instance with a generated remote path

---

named_remote()

@classmethod
def named_remote(
    name: str
) - > [File](file.md?sid=flyte_io__file_file)[T]

Create a File reference whose remote path is derived deterministically from name.

Parameters

Name	Type	Description
name	str	Plain filename (e.g., "data.csv"). Must not contain path separators.

Returns

Type	Description
[File](file.md?sid=flyte_io__file_file)[T]	A File instance whose path is stable across retries.

---

from_existing_remote()

@classmethod
def from_existing_remote(
    remote_path: str,
    file_cache_key: Optional[str]
) - > [File](file.md?sid=flyte_io__file_file)[T]

Create a File reference from an existing remote file.

Parameters

Name	Type	Description
remote_path	str	The remote path to the existing file
file_cache_key	Optional[str]	Optional hash value to use for cache key computation. If not specified, the cache key will be computed based on the file's attributes (path, name, format).

Returns

Type	Description
[File](file.md?sid=flyte_io__file_file)[T]	A new File instance pointing to the existing remote file

---

open()

@classmethod
def open(
    mode: str,
    block_size: Optional[int],
    cache_type: str,
    cache_options: Optional[dict],
    compression: Optional[str]
) - > AsyncGenerator

Asynchronously open the file and return a file-like object.

Parameters

Name	Type	Description
mode	str	The mode to open the file in (default: 'rb'). Common modes: 'rb' (read binary), 'wb' (write binary), 'rt' (read text), 'wt' (write text)
block_size	Optional[int]	Size of blocks for reading in bytes. Useful for streaming large files.
cache_type	str	Caching mechanism to use ('readahead', 'mmap', 'bytes', 'none')
cache_options	Optional[dict]	Dictionary of options for the cache
compression	Optional[str]	Compression format or None for auto-detection

Returns

Type	Description
AsyncGenerator	An async file-like object that can be used with async read/write operations

---

exists()

@classmethod
def exists() - > bool

Asynchronously check if the file exists.

Returns

Type	Description
bool	True if the file exists, False otherwise

---

exists_sync()

@classmethod
def exists_sync() - > bool

Synchronously check if the file exists.

Returns

Type	Description
bool	True if the file exists, False otherwise

---

open_sync()

@classmethod
def open_sync(
    mode: str,
    block_size: Optional[int],
    cache_type: str,
    cache_options: Optional[dict],
    compression: Optional[str]
) - > Generator

Synchronously open the file and return a file-like object.

Parameters

Name	Type	Description
mode	str	The mode to open the file in (default: 'rb'). Common modes: 'rb' (read binary), 'wb' (write binary), 'rt' (read text), 'wt' (write text)
block_size	Optional[int]	Size of blocks for reading in bytes. Useful for streaming large files.
cache_type	str	Caching mechanism to use ('readahead', 'mmap', 'bytes', 'none')
cache_options	Optional[dict]	Dictionary of options for the cache
compression	Optional[str]	Compression format or None for auto-detection

Returns

Type	Description
Generator	A file-like object that can be used with standard read/write operations

---

download()

@classmethod
def download(
    local_path: Optional[Union[str, Path]]
) - > str

Asynchronously download the file to a local path.

Parameters

Name	Type	Description
local_path	Optional[Union[str, Path]]	The local path to download the file to. If None, a temporary directory will be used and a path will be generated.

Returns

Type	Description
str	The absolute path to the downloaded file

---

download_sync()

@classmethod
def download_sync(
    local_path: Optional[Union[str, Path]]
) - > str

Synchronously download the file to a local path.

Parameters

Name	Type	Description
local_path	Optional[Union[str, Path]]	The local path to download the file to. If None, a temporary directory will be used and a path will be generated.

Returns

Type	Description
str	The absolute path to the downloaded file

---

from_local_sync()

@classmethod
def from_local_sync(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    hash_method: Optional[HashMethod | str]
) - > [File](file.md?sid=flyte_io__file_file)[T]

Synchronously create a new File object from a local file by uploading it to remote storage.

Parameters

Name	Type	Description
local_path	Union[str, Path]	Path to the local file
remote_destination	Optional[str]	Optional remote path to store the file. If None, a path will be automatically generated.
hash_method	`Optional[HashMethod	str]`

Returns

Type	Description
[File](file.md?sid=flyte_io__file_file)[T]	A new File instance pointing to the uploaded remote file

---

from_local()

@classmethod
def from_local(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    hash_method: Optional[HashMethod | str]
) - > [File](file.md?sid=flyte_io__file_file)[T]

Asynchronously create a new File object from a local file by uploading it to remote storage.

Parameters

Name	Type	Description
local_path	Union[str, Path]	Path to the local file
remote_destination	Optional[str]	Optional remote path to store the file. If None, a path will be automatically generated.
hash_method	`Optional[HashMethod	str]`

Returns

Type	Description
[File](file.md?sid=flyte_io__file_file)[T]	A new File instance pointing to the uploaded remote file

---