Module leapyear

The LeapYear Client connects the python API to the LeapYear server.

While connected to the server, the connection information is stored in a resource manager, so direct access to the client is not necessary for all operations.

The main objects that can be directly accessed by the Client object are databases, users and permissions resources. Many resources are cached to reduce network latency, however the load() methods for resource objects will force refreshing of the metadata.

>>> from leapyear import Client
>>> from leapyear.admin import Database, Table, ColumnDefinition

Connecting to the server

• Method 1 - manually open and close the connection.

>>> SERVER_URL = 'https://ly-server:4401'
>>> client = Client(url=SERVER_URL)
>>> print(client.databases)
{}
>>> client.close()

• Method 2 - Use a context to automatically close the connection.

>>> with Client(url=SERVER_URL) as client:
...     print(client.databases)
{}

Create a User

There are two ways to create an object on the LeapYear server. The first is to invoke the Client.create() method.

>>> with Client(url=SERVER_URL) as client:
...     client.create(User('new_user', 'password'))

The second is to call the create() method on the object.

>>> with Client(url=SERVER_URL) as client:
...     User('new_user', 'password').create()

Create a Database

>>> with Client(url=SERVER_URL) as client:
...     db = Database('db_name')
...     client.create(db)
...     print(db.tables)
{}

Create a Table

>>> TABLE_CREDENTIALS = 'hdfs://path/to/data.parq'
>>> columns = [
>>>    ColumnDefinition('x', type="REAL", bounds=(-3.0, 3.0)),
>>>    ColumnDefinition('y', type="BOOL"),
>>> ]
>>> with Client(url=SERVER_URL) as client:
...     tbl = Table(
...         'tbl_name',
...         columns=columns,
...         credentials=TABLE_CREDENTIALS,
...         database=db,
...     )
...     tbl.create()  

The Client class

class leapyear.client.Client(url='http://localhost:4401', username=None, password=None, *, authenticate=<function ly_login>, default_analysis_caching=True, default_allow_max_budget_allocation=True, public_key_auth=False)

A class that wraps a connection to a LeapYear system.

__init__(url='http://localhost:4401', username=None, password=None, *, authenticate=<function ly_login>, default_analysis_caching=True, default_allow_max_budget_allocation=True, public_key_auth=False)

Initialize a Client object.

Parameters

• url (str) – The URL of LeapYear Core. Automatically set to the value of the LY_API_URL environment variable or http://localhost:4401 if not specified.

• username (Optional[str]) – Optional username to pass to the authenticate parameter

• password (Optional[str]) – Optional password to pass to the authenticate parameter

• authenticate (AuthenticateFn) – A callback that should log in the user and return a LeapYear token. By default, logs in with the username and password of a LeapYear user, if username and password are provided. Otherwise, uses the token in the LY_JWT environment variable.

• default_analysis_caching (bool) – Whether to cache analysis results by default.

• default_allow_max_budget_allocation (bool) – Whether to allow running analyses on data sets that will automatically consume near the maximum privacy exposure per computation. If enabled, computations on small data sets that use the maximum privacy exposure will be blocked by default. This behavior can be overwritten at the computation level.

• public_key_auth (bool) – Use public key auth to authenticate requests to the LeapYear API. Requires setup via the API setup instructions.

Raises

• AuthenticationError – when login fails.

• InvalidURL – when the url parameter is formatted incorrectly.

close()

Close the LeapYear connection.

Return type

None

logout()

Logout and prevent any further actions using the current token.

Return type

None

clear_analysis_cache()

Clear all analyses from the cache.

Return type

None

clear_all_caches()

Clear all of the caches.

Return type

None

count_analysis_cache()

Return the number of analyses in the analysis cache.

Return type

int

unpersist_all_relations()

Clear all cached datasets.

Unsupported Backends

Not supported for the following LeapYear compute backend(s): snowflake.

Return type

None

property logger

Get the Logger object for the client.

Return type

Logger

property url

Get the URL of the connection.

Return type

str

property username

Get the user currently logged in the server.

Return type

str

property connected

Check if the client can successfully connect + authenticate to the LeapYear system.

Return type

bool

property status

Get the status of the Client’s connection to the LeapYear system.

Return type

ClientStatus

create(obj, ignore_if_exists=False, drop_if_exists=False)

Create an object on the LeapYear server.

Return type

None

create_async(obj)

Create an object on the LeapYear server asynchronously.

Return type

AsyncJob

update(obj, **kwargs)

Update an object on the LeapYear server.

Return type

None

drop(obj, ignore_missing=False)

Drop an object on the LeapYear server.

Return type

None

property privacy_profiles

Get all privacy profiles available on the server.

Return type

Mapping[str, PrivacyProfile]

property databases

Get all databases available on the server.

Return type

Mapping[str, Database]

property current_user

Get the currently logged in user.

Return type

User

property users

Get users available on the server.

Return type

Mapping[str, User]

property groups

Get groups available on the server.

Return type

Mapping[str, Group]

property jobs

Get running jobs on the server.

Return type

List[AsyncJobInformation]

property recent_finished_jobs

Get the most recent finished jobs on the server.

Return type

List[AsyncJobInformation]