citrine.resources.file_link module

A collection of FileLink objects.

class citrine.resources.file_link.CsvColumnInfo(name: str, bounds: BaseBounds, exact_range_bounds: BaseBounds)

Bases: Serializable

The info for a CSV Column, contains the name, recommended and exact bounds.

classmethod build(data: dict) → Self: Build an instance of this object from given data.

dump() → dict: Dump this instance.

bounds = None

recommended bounds of the column (might include some padding)

Type:: BaseBounds

exact_range_bounds = None

exact bounds of the column

Type:: BaseBounds

name = None

name of the column

Type:: str

class citrine.resources.file_link.FileCollection(*args, session: Session | None = None, dataset_id: UUID | None = None, team_id: UUID | None = None, project_id: UUID | None = None)

Bases: Collection[FileLink]

Represents the collection of all file links associated with a dataset.

build(data: dict) → FileLink: Build an instance of FileLink.

delete(file_link: FileLink)

Delete the file associated with a given FileLink from the database.

Parameters:: file_link (FileLink) – Resource referencing the external file.

download(*, file_link: str | UUID | FileLink, local_path: str | Path)

Download the file associated with a given FileLink to the local computer.

Parameters:

file_link (FileLink, str, UUID) – Resource referencing the file.
local_path (str, Path) – Path to save file on the local computer. If local_path is a directory, then the filename of this FileLink object will be appended to the path.

get(uid: UUID | str, *, version: UUID | str | int | None = None) → FileLink

Retrieve an on-platform FileLink from its filename or file uuid.

Parameters:

uid (Union[UUID, str]) – A representation of the FileLink (Citrine id or file name)
version (Optional[UUID, str, int]) – The version, as a UUID or str(UUID) of the version_id or an int or str(int) of the version number. If None, returns the file with the highest version number (most recent).

Returns:

An object with specified scope and uid

Return type:

ResourceType

ingest(files: Iterable[FileLink | Path | str], *, upload: bool = False, raise_errors: bool = True, build_table: bool = False, delete_dataset_contents: bool = False, delete_templates: bool = True, timeout: float = None, polling_delay: float | None = None, project: Project | UUID | str | None = None) → IngestionStatus

[ALPHA] Ingest a set of CSVs and/or Excel Workbooks formatted per the gemd-ingest protocol.

Parameters:

files (List[FileLink, Path, or str]) – A list of files from which GEMD objects should be built. A FileLink must contain an absolute URL or a relative path for an on-platform resource. Strings must be resolvable to a FileLink; if resolution fails, an exception is thrown. * If upload is False, an attempt is made to resolve it to an on-platform resource. * If upload is True, resolves locally first, and falls back to on-platform.
upload (bool) – If the files are off-platform references, upload them first. Defaults to False, in which case an off-platform resource raises an error. A file is off-platform if it has an absolute URL and that URL is not for the citrine platform. For example, https://example.com/file.csv is off-platform, and would be uploaded to platform and ingested if upload is True.
raise_errors (bool) – Whether ingestion errors raise exceptions (vs. simply reported in the results). Default: True
build_table (bool) – Whether to trigger a regeneration of the table config and building the table after ingestion. Default: False
project (Optional[Project, UUID, or str]) – Which project to use for table build if build_table is True.
delete_dataset_contents (bool) – Whether to delete old objects prior to creating new ones. Default: False
delete_templates (bool) – Whether to delete old templates if deleting old objects. Default: True
timeout (Optional[float]) – Amount of time to wait on the job (in seconds) before giving up. Note that this number has no effect on the underlying job itself, which can also time out server-side.
polling_delay (Optional[float]) – How long to delay between each polling retry attempt.

Returns:

The result of the ingestion operation.

Return type:

IngestionStatus

list(*, per_page: int = 100) → Iterator[ResourceType]

Paginate over the elements of the collection.

Leaving page and per_page as default values will yield all elements in the collection, paginating over all available pages.

Parameters:: per_page (int, optional) – Max number of results to return per page. Default is 100. This parameter is used when making requests to the backend service. If the page parameter is specified it limits the maximum number of elements in the response.
Returns:: An iterator that can be used to loop over all the resources in this collection. Use list() to force evaluation of all results into an in-memory list.
Return type:: Iterator[ResourceType]

read(*, file_link: str | UUID | FileLink) → bytes

Read the file associated with a given FileLink.

Parameters:: file_link (FileLink, str, UUID) – Resource referencing the file.
Returns:: The contents of the file.
Return type:: I/O stream

register(model: CreationType) → CreationType: Create a new element of the collection by registering an existing resource.

update(model: CreationType) → CreationType: Update a particular element of the collection.

upload(*, file_path: str | Path, dest_name: str | None = None) → FileLink

Uploads a file to the dataset.

Parameters:

file_path (str, Path) – The path to the file on the local computer.
dest_name (str, optional) – The name the file will have after being uploaded. If unspecified, the local name of the file will be used. That is, the file at “/Users/me/diagram.pdf” will be uploaded with the name “diagram.pdf”. File names must be unique within a dataset. If a file is uploaded with the same dest_name as an existing file it will be considered a new version of the existing file.

Returns:

The filename and url of the uploaded object.

Return type:

FileLink

class citrine.resources.file_link.FileLink(filename: str, url: str)

Bases: GEMDResource[FileLink], FileLink

Resource that stores the name and url of an external file.

Parameters:

filename (str) – The name of the file.
url (str) – URL that can be used to access the file.

access_control_dict() → dict: Return an access control entity representation of this resource. Internal use only.

as_dict() → dict

Dump to a dictionary (useful for interoperability with gemd).

Because of the _key mapping in Property, __dict__’s keys are fundamentally different between gemd.entity.dict_serializable and this class. This means we can’t just use gemd’s as_dict for comparisons.

classmethod build(data: dict) → GEMDSelf: Convert a raw, nested dictionary into Objects.

dump() → dict: Dump this instance.

classmethod from_dict(d: Mapping[str, Any]) → DictSerializableType

Reconstitute the object from a dictionary.

Parameters:: d (dict) – The object as a dictionary of key-value pairs that correspond to the object’s fields.
Returns:: The deserialized object.
Return type:: DictSerializable

classmethod from_path(path: str | Path) → FileLink: Construct a FileLink from a local Path.

created_by = None

Unique uuid4 identifier of this User who loaded this file.

Type:: UUID

created_time = None

Time the file was created on platform.

Type:: datetime

description = None

A human-readable description of the file.

Type:: str

filename = None

mime_type = None

Encoded string representing the type of the file (IETF RFC 2045).

Type:: str

property name: Attribute name is an alias for filename.

size = None

Size in bytes of the file.

Type:: int

skip = {}

typ = 'file_link'

uid = None

Unique uuid4 identifier of this file; consistent across versions.

Type:: UUID

url = None

version = None

Unique uuid4 identifier of this version of this file.

Type:: UUID

version_number = None

How many times this file has been uploaded; files are the “same” if they share a filename and dataset.

Type:: int

class citrine.resources.file_link.FileLinkMeta(name, bases, *args, typ: str | None = None, skip: Set[str] = frozenset({}), **kwargs)

Bases: DictSerializableMeta

Metaclass for FileLink deserialization.

mro(): Return a type’s method resolution order.

register(subclass)

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

property class_mapping: Dict[str, type]

Return class typ string -> class map for DictSerializable and its descendants.

Note that is actually returns a copy of the internal dict to avoid accidental breakage.

Returns:: The mapping from typ string to class
Return type:: Dict[str, type]

class citrine.resources.file_link.SearchFileFilterTypeEnum(value)

Bases: BaseEnumeration

The type of the filter used to search for files.

SEARCH_BY_NAME:
Search a file by name in a specific dataset, returns by default the last version or a specific one
SEARCH_BY_VERSION_ID:
Search by a specific file version id
SEARCH_BY_DATASET_FILE_ID:
Search either the last version or a specific version number for a specific dataset file id

DATASET_FILE_ID_SEARCH = 'search_by_dataset_file_id'

NAME_SEARCH = 'search_by_name'

VERSION_ID_SEARCH = 'search_by_version_id'