base
This module deals with the connection to the engine server. To set up a
connection, it is recommended to manually invoke the connect function
before performing any operations in crandas. This function returns a new
Session object, that stores parameters about the connection.
import crandas as cd
session = cd.connect("default") # This looks for `default.vdlconn`
cd.DataFrame({})
Depending on the connection file, the connection is made in design mode or in authorized mode. The used mode can be inspected by printing it:
There is one global active Session object, called session.
Whenever connect is called, this variable is updated to reflect the new
session object. Any operation, such as creating or opening a DataFrame,
happens in the global session, except when a session is specified as a keyword
argument. To temporarily set the default session to my_session, use
my_session as a context handler, e.g.,
When the user does not call connect manually, Session.connect
is lazily invoked on the existing Session object as soon as the user issues
their first crandas command that needs a connection to the engine server, like
uploading a table. Because of this, the user can also set configuration
parameters by modifying the existing global Session object, prior to issuing
any crandas commands:
import crandas as cd
from crandas.base import session
from pathlib import Path
session.endpoint = "https://my-vdl-cluster:8920/api/v1"
session.base_path = Path("/my/vdl/path")
table = cd.DataFrame({})
Next to the choice between actively calling connect with parameters, or
changing the existing Session object variables, the user also has a choice
between using the connection file (recommended), and specifying the
endpoint and base_path (legacy method). See Session for details.
DesignModeWarning
Bases: UserWarning
Warning that the server is running in design mode. Can be disabled via warn_design setting
Session(base_path=None, insecure_one_party_mode=False, mode=None, analyst_key=None, keepalive=None, endpoint=None, api_token=None, override_version_check=False, **kwargs)
This object stores the state specific to the connection to the engine
server. To configure the connection, it is recommended to use the
connect function, that initializes a fresh instance of this class.
There are two ways to configure the connection: using a connection file (recommended, new default), or by manually specifying an URL endpoint and a base folder that contains all required key material (legacy approach).
If the user does not specify a connection file nor a base path
explicitly, the default behavior is to look for the default.vdlconn
file (overridable through the default_connection_file variable, see
crandas.config), inside of the configuration folder.
If it is not present, the configuration folder is
scanned for files with the .vdlconn extension. If there is a single
connection file, that file is used. If there are multiple connection files,
the system does not know which file to choose and it raises a
ConnectionFileError.
Besides the connection file, the system needs an analyst key when
connecting to a cluster that is in authorized mode. By default, the analyst
key is taken from analyst.sk from the configuration folder (unless
legacy mode is used, then it is clientsign.sk for backwards
compatibility). It can be configured using the analyst_key argument:
import crandas as cd
from pathlib import Path
session = cd.connect("default", analyst_key=Path("/path/to/my/analyst.sk"))
crandas.DataFrame({})
The user can also specify the server endpoint and key material manually
(legacy approach). When the user changes the endpoint attribute of
an existing Session object, that Session object is set to legacy mode. In
legacy mode, the key material is read from files that are specified
relative to the base_path attribute. Note that if the
connect method is not actively called by the user, it is lazily
called on the first crandas method that requires a connection to the engine.
This provides a way to first configure the variables in legacy mode; for
example:
import crandas as cd
from crandas.base import session
session.endpoint = "https://example.com:10000/api/v1"
session.base_path = Path("/cranmera")
session.authorized_mode = False
cd.DataFrame({})
The session can be used as a context handler to temporarily change the global
session variable cd.base.session, e.g.:
session1 = cd.base.connect("session1")
session2 = cd.base.connect("session2")
cd.DataFrame() # happens in session2
cd.DataFrame(session=session1) # happens in session1
with session1:
cd.DataFrame() # happens in session1
cd.DataFrame(session=session2) # happens in session2
| RAISES | DESCRIPTION |
|---|---|
EngineError
|
Passes through error from engine and appropriate error code |
EngineError
|
Passes through error from engine in case error code is not known |
| PARAMETER | DESCRIPTION |
|---|---|
base_path
|
When using the legacy settings mode (see
TYPE:
|
insecure_one_party_mode
|
if True, allow connecting to the insecure one party mode, which is strictly for testing purposes
TYPE:
|
mode
|
Sets the mode ('design' or 'authorized') in case the connection file does not do so
TYPE:
|
analyst_key
|
Specifies the analyst key. See
TYPE:
|
keepalive
|
Specify whether to use HTTP Keep-Alive in the connection to the engine server, overriding the setting in the connection file
DEFAULT:
|
override_version_check
|
If True, do not check that the server version is compatible with the version of crandas.
TYPE:
|
analyst_key
property
writable
The (secret) signing key that the analyst that executes a query will use to sign its query. Approvers will incorporate the corresponding public key into their query approval, which ensures that only the designated analyst will be able to execute the query.
It may be set to either a crandas.sign.SigningKey instance, or a Path
(or string path) pointing to such a file, or None to load the default
key. Paths, or string paths containing a slash (/), are treated as
relative to the current working directory. String paths not containing
a slash are assumed to refer to a filename inside of the configuration
folder (using a connection file) or the base_path (legacy mode, for
backwards compatibility).
If no analyst_key is specified, the default behavior is to load
analyst.sk in the configuration folder when using a connection
file, or clientsign.sk in the base_path in legacy mode, for
backwards compatibility reasons.
authorized_mode
property
writable
Returns whether to use authorized mode
base_path = base_path
instance-attribute
property
writable
The base 'cranmera' folder. When None, the application tries to find a parent of the current
directory called 'cranmera', or defaults to the current directory. This
is only used in legacy mode, see settings_mode.
design_mode
property
writable
Returns whether to use design mode
endpoint = endpoint
instance-attribute
property
writable
The endpoint URL of the engine server. This is only used in the legacy mode
where the endpoint and all certificates and server public keys are
specified manually. See Session for details.
keepalive
property
mode
property
writable
Returns mode ("design" or "authorized")
settings_mode = SettingsMode.CONNECTION_FILE
class-attribute
instance-attribute
Specifies whether the Session object uses a connection file (recommended,
new default) to establish a connection, or whether the endpoint is
specified manually (legacy approach). In the legacy approach, all key
material is found in files specified relative to the
base_path .
absolute_certificate_path()
The path to the engine endpoint certificate, as an absolute path.
connect(connection_file=None, mode=None)
Establishes a connection with the query server and verifies whether the client and server versions are compatible.
To disable the version check, set override_version_check to
True, or set the environment variable
CRANDAS_OVERRIDE_VERSION_CHECK=1.
The connect function can only be called once on a Session
object. To re-connect, use the free function connect().
| PARAMETER | DESCRIPTION |
|---|---|
connection_file
|
A (path to a) connection file. It may be specified as string not containing slashes (/),
backslashes () or dots (.), in which case it is interpreted as a
If it is a string that contains slashes, backslashes or dots, it is assumed to be a path, either a relative path for the current working directory, or an absolute path. If it is True, load the default connection file.
TYPE:
|
mode
|
Specifies the mode ('design' or 'authorized') in case the connection file does not do so
TYPE:
|
connect(connection_file=None, *, set_global_session=True, mode=None, **session_args)
Connect to the engine using a connection file.
Creates a new Session with the specified arguments and then calls
Session.connect
Note
This function is also available as crandas.connect().
| PARAMETER | DESCRIPTION |
|---|---|
connection_file
|
Connection file to use, see
DEFAULT:
|
set_global_session
|
Specifies whether to overwrite the global session variable
TYPE:
|
mode
|
Sets the mode (
TYPE:
|
**session_args
|
Arguments to
DEFAULT:
|
| RETURNS | DESCRIPTION |
|---|---|
Session
|
The newly created |