Module leapyear.admin

Administrative objects for LeapYear.

Types

class leapyear.admin.Type

LeapYear types factory.

These methods are helpers to create instances of the LeapYear types. The types are BOOL, INT, REAL, FACTOR, TEXT, DATE, and DATETIME, each with nullable variants. Nullable types allow missing or unknown data.

static NULL()

Create a void type on the LeapYear system.

A column can only have this type if there are no rows in the table.

Return type

Type

static NULL_NULL()

Create a void nullable type on the LeapYear system.

A column with this type contains only nulls.

Return type

Type

static BOOL()

Create a boolean type on the LeapYear system.

Return type

Type

static NULL_BOOL()

Create a boolean nullable type on the LeapYear system.

Return type

Type

static INT(lo, hi)

Create an integer type on the LeapYear system.

Parameters
  • lo (int) – Lower bound for the integers.

  • hi (int) – Upper bound for the integers.

Return type

Type

static NULL_INT(lo, hi)

Create an integer nullable type for the LeapYear system.

Parameters
  • lo (int) – Lower bound for the integers.

  • hi (int) – Upper bound for the integers.

Return type

Type

static REAL(lo, hi)

Create a real (floating-point) type for the LeapYear system.

Parameters
  • lo (float) – Lower bound for the reals.

  • hi (float) – Upper bound for the reals.

Return type

Type

static NULL_REAL(lo, hi)

Create a real (floating-point) nullable type for the LeapYear system.

Parameters
  • lo (float) – Lower bound for the reals.

  • hi (float) – Upper bound for the reals.

Return type

Type

static FACTOR(options)

Create a factor type for the LeapYear system.

Factor types have values from a fixed set of strings.

Parameters

options (Set[Factor]) – Set of factor values.

Return type

Type

static NULL_FACTOR(options)

Create a factor type for the LeapYear system that permit null values.

Factor types have values from a fixed set of strings.

Parameters

options (Set[Factor]) – Set of factor values.

Return type

Type

static TEXT()

Create a free text type on the LeapYear system.

Return type

Type

static NULL_TEXT()

Create a free text nullable type on the LeapYear system.

Return type

Type

static IMPLICITFACTOR()

Create an implicit factor type on the LeapYear system.

Return type

Type

static NULL_IMPLICITFACTOR()

Create an implicit facotor nullable type on the LeapYear system.

Return type

Type

static DATE(lo, hi)

Create a date type for the LeapYear system.

Parameters
  • lo (date) – The lower bound of dates.

  • hi (date) – The upper bound of dates.

Return type

Type

static NULL_DATE(lo, hi)

Create a date type for the LeapYear system that permits null values.

Parameters
  • lo (date) – The lower bound of dates.

  • hi (date) – The upper bound of dates.

Return type

Type

static DATETIME(lo, hi)

Create a datetime type for the LeapYear system.

Parameters
  • lo (datetime) – The lower bound for datetimes.

  • hi (datetime) – The upper bound for datetimes.

Return type

Type

static NULL_DATETIME(lo, hi)

Create a datetime type for the LeapYear system that permits null values.

Parameters
  • lo (datetime) – The lower bound for datetimes.

  • hi (datetime) – The upper bound for datetimes.

Return type

Type

classmethod isinstance(obj, class_or_tuple, _nullcomparefunc=<function Type.<lambda>>)

Check if a type is an instance of a specific LeapYear type.

Parameters
  • obj (Type) – The LeapYear type

  • class_or_tuple (Any) –

  • _nullcomparefunc (Callable[[bool, bool], bool]) – Comparison function for null values.

Return type

bool

classmethod issupertype(obj, class_or_tuple)

Check if type B is either type A or non-nullable A.

Parameters
  • obj (Type) – The LeapYear type

  • class_or_tuple (Any) –

Return type

bool

classmethod isclose(obj1, obj2, rtol=1e-05, atol=1e-08)

Check if two types including their bounds are approximately equal.

Return type

bool

Database class

class leapyear.admin.Database(name, description=None, privacy_profile=None, privacy_limit=None, db_id=None)

Database object.

classmethod all()

Get all databases.

Returns

Iterator over all of the databases available on the server.

Return type

all_databases

property id

Get the ID.

Return type

int

property tables

Get the tables of the database.

Return type

Mapping[str, Table]

property views

Get the views of the database.

This property can only be seen by admins

Return type

Mapping[str, View]

property privacy_params

Get the privacy parameter of the database.

Return type

PrivacyProfileParams

property description

Get the database’s description.

Return type

Optional[str]

property privacy_profile

Get the database’s Privacy Profile.

Return type

NewType()(PrivacyProfileIdentifier, str)

get_privacy_limit()

Get the database’s privacy limit.

Return type

PrivacyLimit

set_privacy_limit(privacy_limit)

Set the database’s privacy limit.

Return type

None

property identifier

Get the database identifier.

Return type

NewType()(DatabaseIdentifier, str)

create()

Create an object.

Return type

Persistent[~Id, ~ShowR]

create_async()

Create an object.

Return type

NewType()(AsyncJobId, str)

drop()

Drop an object.

Return type

None

get_access(subject=None)

Get the access level of the given subject.

Parameters

subject (Union[User, Group, None]) – A User or Group object. If none is provided, use the currently logged in user.

Return type

~AccessType

load()

Load an object.

Return type

Persistent[~Id, ~ShowR]

property name

Return the name of this object.

Return type

str

set_access(subject, access)

Grant the given access level to a subject.

Parameters
  • subject (Union[User, Group]) – A User or Group object.

  • access (~AccessType) – The access level to grant.

Return type

None

update(**kwargs)

Update an object.

Return type

Persistent[~Id, ~ShowR]

Table class

class leapyear.admin.Table(name, columns=None, credentials=None, description=None, database=None, cached=False, public=False, num_partitions=None, size=None, table_id=None)

Table object.

property id

Get the ID.

Return type

int

property columns

Get the columns of the table.

Return type

Mapping[str, Column]

property description

Get the table’s description.

Return type

Optional[str]

property database

Get the database the table belongs to.

Return type

str

property public

Identify whether the table is a public table.

Return type

bool

get_privacy_limit()

Show the privacy limit associated with the table.

Returns a value of None when the table is public.

Return type

Optional[PrivacyLimit]

set_privacy_limit(privacy_limit)

Set the privacy limit associated with the table.

Throws a ServerError when the table is public.

Return type

None

property privacy_spent

Show the privacy spent for the current user on this table as a percentage.

Returns the privacy spent (𝜀) associated with all the information disclosed so far by the LeapYear platform to the current user working with this table. The value is represented as a percentage of the privacy limit (0, 10, 20, …100) set by the administrator. The value can exceed 100% if the admin forcibly lowers the privacy limit below the current user’s privacy spent. No queries can be run on a table where the privacy spent is at or above 100%.

If the table is public, returns None instead.

Returns

Privacy exposure, expressed as a percentage of the limit.

Return type

float

Examples

  1. Review the current level of privacy spent.

>>> from leapyear.admin import Database, Table
>>> db = Database('db')
>>> t = Table('table', database=db)
>>> print(t.privacy_spent)
50
get_user_privacy_spent(user)

Show the privacy spent for a user on this table.

Returns the privacy spent (𝜀), as a float, associated with all the information disclosed so far by the LeapYear platform to a user working with this table, and the privacy limit as an (𝜀, 𝛿) pair in a PrivacyLimit object.

Returns None instead, if the table is public.

This method is only available to authorized administrators, or to a user attempting to retreive their own privacy spent.

Return type

Optional[Tuple[float, PrivacyLimit]]

set_user_privacy_limit(user, privacy_limit, force_lower_than_exposure_level=False)

Allow the administrator to set the privacy limit for a user on this table.

Sets the privacy limit as a (𝜀, 𝛿) pair in a PrivacyLimit object for the user, on this table, that is considered acceptable by the administrator. If this method is not called, the user uses the privacy limit from the table.

If this is called with a public table, nothing happens.

This method is only available to authorized users with system admin privileges.

Return type

None

property identifier

Get the Table identifier.

Return type

TableIdentifier

set_all_columns_access(subject, access)

Set the given access for all columns in the table.

If the table is public, the only legal access levels are full access and no access. Setting any other value will result in an error.

property slices

Show Data Slices for the table.

Return type

List[DataSlice]

add_data_slice(file_credentials, update_column_bounds=False, num_partitions=None, description='')

Add a file to the list of data slices of the table.

Return type

None

show_slice_schemas(begin=0, endIncluded=None)

Show slice schemas in a range by positional index starting with 0.

Parameters
  • begin (int) – Lower end of the slice range.

  • endIncluded (Optional[int]) – Upper end of the slice range. None means the last slice index.

Return type

List[List[Type]]

create()

Create an object.

Return type

Persistent[~Id, ~ShowR]

create_async()

Create an object.

Return type

NewType()(AsyncJobId, str)

drop()

Drop an object.

Return type

None

load()

Load an object.

Return type

Persistent[~Id, ~ShowR]

property name

Return the name of this object.

Return type

str

update(**kwargs)

Update an object.

Return type

Persistent[~Id, ~ShowR]

Column class

class leapyear.admin.Column(name, typ=None, description=None, table=None, col_id=None)

Column object.

property id

Get the ID.

Return type

int

property table

Get the table that the column belongs to.

Return type

str

property database

Get the database that the column belongs to.

Return type

str

property type

Get the type of the Column.

Return type

Type

property description

Get the description of the Column.

Return type

Optional[str]

get_access(subject=None)

Get the access level of the given subject.

Parameters

subject (Union[User, Group, None]) – A User or Group object. If none is provided, use the currently logged in user.

Return type

~AccessType

property name

Return the name of this object.

Return type

str

set_nullable(nullable)

Set the Column’s type nullability.

Return type

None

property identifier

Return the column identifier.

set_access(subject, access)

Grant the given access level to the column.

If this is a column of a public table, only Full Access and No Access are legal values. Setting any other value will result in an error.

Return type

None

View class

class leapyear.admin.View(name, database, relation, num_partitions=1, partitioning_columns=[], sort_within_partitions_by_columns=[], nominal_partitioning_columns=[], description=None)

View object.

A view is a dataset that can be persisted on disk (materialized), across restarts of the LeapYear application. Analysts referencing a materialized view will be using the dataset that is on disk, instead of re-calculating any transformations defined on the dataset.

A guide on how to use views can be found here.

Analysts should reference views with a ViewIdentifier object, for example:

>>> from leapyear import DataSet
>>> from leapyear.admin import ViewIdentifier
>>> view = ViewIdentifier(viewName=view_name, database=db_object)
>>> ds = DataSet.from_view(view)
Parameters
  • name (NewType()(ViewName, str)) – The view’s name. Views must have unique names, including de-materialized views. View names cannot include any of these characters: ,;{}()=", or newlines (\n), or tabs (\t)

  • database (NewType()(DatabaseIdentifier, str)) – The database that the view belongs to. This should be the database that the tables referenced in the DataSet belong to.

  • relation – The DataSet that will be stored as a view.

  • num_partitions – The number of partitions that the view will be split into. This will only be used if partitioning_columns is also set.

  • partitioning_columns – The columns by which to bucket (cluster) the view into partitions. This must be used with num_partitions. The view will have num_partitions number of partitions, and records with the same values for the partitioning_columns will be in the same partition.

  • sort_within_partitions_by_columns – The columns used to sort rows within each partition.

  • nominal_partitioning_columns – The columns by which to partition the view. This should be used by itself, without any other partition parameters.

  • description (Optional[str]) – Description of the view.

property database

Get the database associated to the view.

Return type

str

property description

Get the description associated to the view.

Return type

str

dematerialize()

Dematerialize the view.

This is the preferred method to free disk space used by a view.

property identifier

Get the View identifier.

Return type

ViewIdentifier

create()

Create an object.

Return type

Persistent[~Id, ~ShowR]

create_async()

Create an object.

Return type

NewType()(AsyncJobId, str)

drop()

Drop an object.

Return type

None

load()

Load an object.

Return type

Persistent[~Id, ~ShowR]

property name

Return the name of this object.

Return type

str

update(**kwargs)

Update an object.

Return type

Persistent[~Id, ~ShowR]

User class

class leapyear.admin.User(username, password=None, *, is_root=None, enabled=None, user_id=None, subj_id=None)

User object.

classmethod all()

All Users.

Returns

All users on the LeapYear server.

Return type

Iterator[User]

property id

Get the ID.

Return type

int

property subj_id

Get the subject ID.

Return type

int

property username

Get the username.

Return type

str

property is_root

Whether the user is a root user.

Return type

bool

property enabled

Whether the user is enabled.

Return type

bool

property groups

Get the groups of a user.

Returns

All groups of the user on the LeapYear server.

Return type

List[Group]

property identifier

Identifier.

Return type

NewType()(UserIdentifier, str)

create()

Create an object.

Return type

Persistent[~Id, ~ShowR]

create_async()

Create an object.

Return type

NewType()(AsyncJobId, str)

drop()

Drop an object.

Return type

None

load()

Load an object.

Return type

Persistent[~Id, ~ShowR]

property name

Return the name of this object.

Return type

str

update(**kwargs)

Update an object.

Return type

Persistent[~Id, ~ShowR]

Privacy Profile class

class leapyear.admin.PrivacyProfile(name, param, hidden=False, description='')

PrivacyProfile object.

property description

Get the privacy profile description.

Return type

str

property hidden

Get the hidden flag for the profile.

True indicates that the profile is hidden in the Data Manager.

Return type

bool

property param

Get the parameters of the privacy profile.

Return type

PrivacyProfileParams

property identifier

Get the identifier of the privacy profile.

Return type

NewType()(PrivacyProfileIdentifier, str)

Permission objects

class leapyear.admin.DatabaseAccessType

AccessType for Databases.

  • NO_ACCESS_TO_DB: Prevents user from accessing database

  • SHOW_DATABASE: Allows a user to see this database and the tables it contains, including their public metadata

  • ADMINISTER_DATABASE: Allows a user to administer this database - e.g. add data sources, grant user access

class leapyear.admin.ColumnAccessType

AccessType for Columns.

  • NO_ACCESS: Prevents user from accessing column

  • COMPUTE: Allows a user to run randomized computations

  • FULL_ACCESS: Allows a user to run randomized computations and view and retrieve raw data