crandas.stateobject

class crandas.stateobject.ObjectProperty(nm)

Bases: object

Property of a StateObject

If the property is not set, an UnknownSchemaError is raised.

The value of the property is set to/gotten from the attribute self.nm, so, e.g., CDataFrame.columns maps to CDataFrame._columns. Accordingly, for example, If the columns of a CDataFrame are not set (so inside a transaction or a dry run), then .columns gives an UnknownSchemaError whereas ._columns returns None (and similarly for .nrows). So the .columns should be used by users, and by functions that really need to know the columns (for example, merge needs to know the names of the columns to be able to formulate its query and cannot do anything otherwise). And we can to use ._columns to enable functions to work in transactions/dry-run mode if they can still do something that makes sense if .columns is None.

class crandas.stateobject.StateObject(**kwargs)

Bases: ResponseHandler, DeferredBase

Base class for VDL state objects.

A VDL state object is an object that is stored remotely in the VDL and on which operations can be performed, such as a CDataFrame.

clone()

Creates a clone of the StateObject. Only needed for objects that can be opened

The clone is used to open the object: when the object is opened, essentially, self.clone().json_to_opened(…) is called.

get_deferred(json_query, *, session)

Called when query is added to a transaction

Parameters:

  • json_q (JSON struct) – Query to be performed (as passed to vdl_query; in particular, with placeholders in place and without the signature used for authorization)

  • session (crandas.base.Session) – Session in which query is executed

Returns:

Return value to be provided to caller of vdl_query

Return type:

Deferred

get_dry_run_result(json_query, *, session)

Called when executing query in dry-run mode

Parameters:

  • json_q (JSON struct) – Query to be performed (as passed to vdl_query; in particular, with placeholders in place and without the signature used for authorization)

  • session (crandas.base.Session) – Session in which query is executed

Returns:

Return value to be provided to caller of vdl_query

Return type:

object

open_dry_run_result()

Return opened version of the object when run in dry-run mode

Should return an object of the same type as json_to_opened.

parse_response(json_query, json_answer, binary_data, prss_nonce, ix, *, session)

Called upon receiving a response to the query from the server

Parameters:

  • json_q (JSON struct) – Query to be performed (as passed to vdl_query; in particular, with placeholders in place and without the signature used for authorization)

  • json_a (JSON struct) – Answer received from server

  • binary_data (binary data stream, see crandas.queries.Query.getdata()) – Stream of binary data for answer

  • prss_nonce (str) – Server-supplied nonce for streaming uploads/downloads

  • ix (int) – Transaction index for masking (0 if not in transaction; otherwise: 1, 2, …)

Returns:

Return value to be provided to caller of vdl_query

Return type:

object

property reference

Obtain a JSON-serializable reference to the object.

remove(**query_args)

Remove object from server

Parameters:

query_args – See queryargs

property result

Returns object

Can be used to retrieve the result of an operation inside a transaction regardless of its mode: if the mode is “open”, then .result needs to be used. Otherwise .result is not needed but this property makes sure it can be used.

save(**query_args)

Save object

Saves the object, e.g., a computation result. As a result of saving, the object is treated in the same way as an upload, meaning e.g. that (depending on the server configuration), the object may remain available after server restarts. See tips_purging.

Saving is supported for various types of object, including tables and table groupings. If the object does not support persistence, an error is raised. In this case, to use the object again, it first needs to be removed and recomputed (e.g., by calling obj.remove() on the object that obj.save() was called on, and then repeating the query used to compute the object).

Parameters:

query_args – See queryargs`

Raises:

cd.errors.ServerError: – The object could not be persisted (see details above)

exception crandas.stateobject.UnknownSchemaError

Bases: RuntimeError

crandas.stateobject.get_upload_handles(get_from=None)

Get list of handles of all objects uploaded to the VDL.

See crandas.stateobject.list_uploads() for an overview of which objects are considerd to be “uploaded”

Parameters:

get_from (str, optional) – If set to “mem”, only return objects that are in the working memory of the VDL server. If set to “disk”, only return objects that are not in the working memory. (The latter causes the objects to be loaded into memory at the server.)

crandas.stateobject.list_uploads(*, also_on_disk=False)

Get list of all objects uploaded to the VDL.

“Uploaded” objects are the results of functions that upload a local dataframe to the VDL, e.g., crandas.crandas.upload_pandas_dataframe(), crandas.crandas.DataFrame(), and crandas.crandas.read_csv(). It does not include tables that are computed from other tables or created via crandas.crandas.demo_table().

By default, for objects that are stored on-disk at the server, the metadata and creation date are not given. See the also_on_disk parameter below.

Parameters:

also_on_disk (bool, default: False) – If set to False, objects that need to be retrieved from disk at the server are listed, but their type and creation date are not returned. If set to True, these objects are loaded into memory and their metadata is returned.

Returns:

Dataframe containing handles, creation date, and type information

Return type:

pd.DataFrame