FileValue

class FileValue(original_path: os.PathLike | None = None, mime_type: str | None = None, encoding: str | None = None, value_id: uuid.UUID | None = None, file_size: int | None = None)

Bases: ansys.tools.variableinterop.variable_value.IVariableValue, abc.ABC

Provides an abstract base class for FileValue implementations.

Overview

Abstract methods

get_reference_to_actual_content_file_async	Realize the file contents to a local filesystem if needed.
get_reference_to_actual_content_file	Realizes the file contents to a local filesystem if needed.

Constructors

is_text_based_static

Determines if a file is text-based via its MIME type.

Methods

accept	Invoke the visitor pattern of this object using the passed-in visitor
to_display_string	Convert the value to a formatted string.
write_file	Write the file’s contents to a new file.
get_contents	Read the contents of the file as a string.
to_api_string	Convert the value to an API string using a save context.
to_api_object	Convert this file to an API object.
get_extension	Get the file extension of the file, including the period.

Properties

variable_type	Variable type of the object.
mime_type	MIME type of the file.
original_file_name	Name of the original file that was wrapped.
extension	Extension of the file.
file_encoding	Encoding of the file.
id	ID of the file.
file_size	Size of the file in bytes if known.
is_text_based	Flag indicating if this file is text-based via its MIME type.

Attributes

BINARY_MIMETYPE
TEXT_MIMETYPE
ORIGINAL_FILENAME_KEY	JSON key for API serialization representing the original file name.
MIMETYPE_KEY
ENCODING_KEY
CONTENTS_KEY
SIZE_KEY

Static methods

read_bom

Open a file for reading and detect a byte order mark at the beginning.

Special methods

__eq__	Return self==value.
__hash__	Return hash(self).

Import detail

from ansys.tools.variableinterop.file_value import FileValue

Property detail

property FileValue.variable_type: VariableType

Variable type of the object.

Returns:

VariableType

Variable type of the object.

property FileValue.mime_type: str

MIME type of the file.

property FileValue.original_file_name: os.PathLike | None

Name of the original file that was wrapped.

property FileValue.extension: str

Abstractmethod:

Extension of the file.

property FileValue.file_encoding: str | None

Encoding of the file.

property FileValue.id: uuid.UUID

ID of the file.

Returns:

UUID

ID that identifies the file.

property FileValue.file_size: int | None

Size of the file in bytes if known.

A value of None indicates that the file size is not known, not that the file size is zero bytes.

property FileValue.is_text_based: bool | None

Flag indicating if this file is text-based via its MIME type.

Returns:

bool

True if the MIME type starts with text or is application/json, False otherwise.

Attribute detail

FileValue.BINARY_MIMETYPE: Final[str] = 'application/octet-stream'

FileValue.TEXT_MIMETYPE: Final[str] = 'text/plain'

FileValue.ORIGINAL_FILENAME_KEY: Final[str] = 'originalFilename'

JSON key for API serialization representing the original file name.

FileValue.MIMETYPE_KEY: Final[str] = 'mimeType'

FileValue.ENCODING_KEY: Final[str] = 'encoding'

FileValue.CONTENTS_KEY: Final[str] = 'contents'

FileValue.SIZE_KEY: Final[str] = 'size'

Method detail

FileValue.__eq__(other)

Return self==value.

FileValue.__hash__()

Return hash(self).

FileValue.accept(visitor: ansys.tools.variableinterop.ivariable_visitor.IVariableValueVisitor[T]) → T

Invoke the visitor pattern of this object using the passed-in visitor implementation.

Parameters:

visitorIVariableValueVisitor

Visitor object to call.

Returns:

T

Results of the visitor invocation.

FileValue.to_display_string(locale_name: str) → str

Convert the value to a formatted string.

Parameters:

locale_namestr

Locale to format the string in.

Returns:

str

String appropriate for use in user-facing areas.

static FileValue.read_bom(filename: str) → str

Open a file for reading and detect a byte order mark at the beginning.

Parameters:

filenamestr

File to read.

Returns:

str

If the file contains a BOM, an appropriate encoding is returned. If the file does not contain a BOM, None is returned.

async FileValue.write_file(file_name: os.PathLike) → None

Write the file’s contents to a new file.

Parameters:

file_namePathLike

Path to the file to create.

Returns:

None

abstract async FileValue.get_reference_to_actual_content_file_async(progress_callback: Callable[[int], None] | None = None) → AsyncLocalFileContentContext

Realize the file contents to a local filesystem if needed.

The FileValue instance is intended to represent an immutable value. The file returned by this call may point to a cached file or even the original file. Callers must not modify the file on disk. Otherwise, undefined behaviors, including class 3 errors, may occur. If the caller needs to modify the file, consider using the write_file method or copying the file before modifying it.

Parameters:

progress_callbackOptional[Callable[[int], None]], optional

Callback that can be called to indicate progress in realizing the local copy. The default is None, in which case this method makes no attempt to report its progress. This method may call a provided callback with a percentage value between 0 and 100 inclusive. The provided callback may not necessarily be called at all, and calls for 0 or 100 percent are not guaranteed, even if other calls occur.

Returns:

AsyncLocalFileContentContext

Context manager that, when exited, deletes the local copy if it is a temporary file.

abstract FileValue.get_reference_to_actual_content_file(progress_callback: Callable[[int], None] | None = None) → LocalFileContentContext

Realizes the file contents to a local filesystem if needed.

The FileValue instance is intended to represent an immutable value. The file returned by this call may point to a cached file or even the original file. Callers must not modify the file on disk. Otherwise, undefined behaviors, including class 3 errors, may occur. If the caller needs to modify the file, consider using the write_file method or copying the file before modifying it.

Parameters:

progress_callbackOptional[Callable[[int], None]], optional

Callback that can be called to indicate progress in realizing the local copy. The default is None, in which case this method makes no attempt to report its progress. This method may call a provided callback with a percentage value between 0 and 100 inclusive. The provided callback may not necessarily be called at all, and calls for 0 or 100 percent are not guaranteed, even if other calls occur.

Returns:

LocalFileContentContext

Context manager that, when exited, deletes the local copy if it is a temporary file.

classmethod FileValue.is_text_based_static(mimetype: str) → bool | None

Determines if a file is text-based via its MIME type.

Parameters:

mimetypestr

File’s MIME type.

Returns:

Optional[bool]

True if the MIME type starts with text or is an application (JSON), False otherwise.

async FileValue.get_contents(encoding: str | None = None) → str

Read the contents of the file as a string.

Parameters:

encodingOptional[str], optional

Encoding to use when reading. The default is None, in which case the current locale’s encoding is used.

Returns:

str

Contents of the file as a string.

FileValue.to_api_string(context: ansys.tools.variableinterop.isave_context.ISaveContext | None = None) → str

Convert the value to an API string using a save context.

Parameters:

contextOptional[ISaveContext], optional

Save context to use. The default value is None, in which case file values are not supported.

Returns:

str

String appropriate for use in files and APIs.

FileValue.to_api_object(save_context: ansys.tools.variableinterop.isave_context.ISaveContext) → Dict[str, str | None]

Convert this file to an API object.

Parameters:

save_contextISaveContext

Save context to use for the conversion.

Returns:

Dict[str, Optional[str]]

API object that matches this FileValue instance.

FileValue.get_extension() → str

Get the file extension of the file, including the period.

If the file extension is not known, .tmp is returned.

Returns:

str

File extension of the file if known, ".tmp" otherwise.