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.
-
static
NULL_INT
(lo, hi)¶ Create an integer nullable type for the LeapYear system.
-
static
REAL
(lo, hi)¶ Create a real (floating-point) type for the LeapYear system.
-
static
NULL_REAL
(lo, hi)¶ Create a real (floating-point) nullable type for the LeapYear system.
-
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
DATE
(lo, hi)¶ Create a date type for the LeapYear system.
-
static
NULL_DATE
(lo, hi)¶ Create a date type for the LeapYear system that permits null values.
-
static
DATETIME
(lo, hi)¶ Create a datetime type for the LeapYear system.
-
static
NULL_DATETIME
(lo, hi)¶ Create a datetime type for the LeapYear system that permits null values.
-
static
ID
()¶ Create an id type on the LeapYear system.
- Return type
Type
-
static
NULL_ID
()¶ Create an implicit facotor nullable type on the LeapYear system.
- 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.
-
classmethod
issupertype
(obj, class_or_tuple)¶ Check if type B is either type A or non-nullable A.
-
static
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
views
¶ Get the views of the database.
This property can only be seen by admins
-
property
privacy_params
¶ Get the privacy parameter of the database.
- Return type
PrivacyProfileParams
-
property
privacy_profile
¶ Get the database’s Privacy Profile.
-
set_privacy_profile
(privacy_profile)¶ Set the database’s privacy profile asynchronously.
- Parameters
privacy_profile (
PrivacyProfile
) – The new privacy profile.
Example
>>> db = c.databases["db1"] >>> pp = c.privacy_profiles["Custom profile 1"] >>> db.set_privacy_profile(pp)
- Return type
-
get_privacy_limit
()¶ Get the database’s privacy limit.
- Return type
PrivacyLimit
-
load
()¶ Load the database.
-
create
()¶ Create the database.
-
update
(**kwargs)¶ Update the database.
-
drop
()¶ Drop the database.
-
get_access
(subject=None)¶ Get the access level of the given subject.
-
set_access
(subject, access)¶ Grant the given access level to a subject.
-
classmethod
Table class¶
-
class
leapyear.admin.
Table
(name, columns=None, credentials=None, description=None, database=None, cached=False, public=False, num_partitions=None, table_id=None)¶ Table object.
-
__init__
(name, columns=None, credentials=None, description=None, database=None, cached=False, public=False, num_partitions=None, table_id=None)¶ Initialize a Table object.
- Parameters
name (
str
) – The table name.columns (
Optional
[List
[ColumnDefinition
]]) – The columns to create the Table with. If no columns provided, the schema will be auto detected from the data.credentials (
Optional
[str
]) – The credentials to the first data slice to be added to the Table.database (
Union
[None
,Database
,NewType()
(DatabaseIdentifier
,str
)]) – The database this table belongs to.cached (
bool
) – Whether the DataFrame representing the table in LY-core should be cached.public (
bool
) – Whether this table should be a public table.num_partitions (
Optional
[int
]) – Repartition the table if set.
-
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
-
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
Examples
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.
-
set_user_privacy_limit
(user, privacy_limit)¶ 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
-
property
identifier
¶ Get the Table identifier.
- Return type
TableIdentifier
-
load
()¶ Load the table.
-
create
()¶ Create the table.
-
update
(**kwargs)¶ Update the table.
-
drop
()¶ Drop the table.
-
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.
-
add_data_slice
(file_credentials, update_column_bounds=False)¶ Add a file to the list of data slices of the table.
- Return type
-
ColumnDefinition class¶
-
class
leapyear.admin.
ColumnDefinition
(name: str, *, type: Union[leapyear.admin.column.ColumnType, str], bounds: Union[None, Tuple[int, int], Tuple[float, float], Tuple[datetime.date, datetime.date], Tuple[datetime.datetime, datetime.datetime], Set[str]] = None, nullable: bool = False, description: Optional[str] = None)¶ The definition of a column for creating a Table with an explicit schema.
Example usage:
>>> table = Table( ... columns=[ColumnDefinition("col1", type="INT", bounds=(0, 10))], ... ... ... ) >>> table.create()
Changing values in a
ColumnDefinition
has no effect after a table is created. See theTableColumn
documentation for functions to update column attributes after creating a table.-
type
¶
-
bounds
¶
-
description
¶ Optional[str]
-
TableColumn class¶
-
class
leapyear.admin.
TableColumn
(table, id, name, type, bounds, nullable, description)¶ A column in a table.
-
property
type
¶ Get the type of the column.
- Return type
ColumnType
-
property
bounds
¶ Get the bounds of the column.
-
update
(**kwargs)¶ Update the Column’s bounds or nullability.
All of the parameters are optional. If anything is not provided, it’s left unchanged.
-
property
identifier
¶ Return the column identifier.
-
get_access
(subject=None)¶ Get the access level of the given subject.
-
set_access
(subject, access)¶ Grant the given access level to a subject.
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.
-
property
-
class
leapyear.admin.
ColumnType
(value)¶ A column type.
-
BOOL
= 'BOOL'¶ A BOOL column has no bounds.
-
INT
= 'INT'¶ An INT column whose bounds should be a
(int, int)
pair.
-
REAL
= 'REAL'¶ A REAL column whose bounds should be a
(float, float)
pair.
-
FACTOR
= 'FACTOR'¶ A FACTOR column whose bounds should be a list of strings.
-
TEXT
= 'TEXT'¶ A TEXT column has no bounds.
-
DATE
= 'DATE'¶ A DATE column whose bounds should be a
(datetime.date, datetime.date)
pair, containing dates of the form1970-01-31
.
-
DATETIME
= 'DATETIME'¶ A DATETIME column whose bounds should be a
(datetime.datetime, datetime.datetime)
pair, containing datetimes of the form1970-01-31T00﹕00﹕00
.
-
ID
= 'ID'¶ An ID column has no bounds.
-
-
leapyear.admin.
ColumnBounds
¶ A type alias representing the union of all possible column bounds described in
ColumnType
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.
-
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
-
load
()¶ Load the view.
-
create
()¶ Create the view.
-
create_async
()¶ Create the view asynchronously.
- Return type
AsyncCreateJob
-
update
(**kwargs)¶ Update the view.
-
drop
()¶ Drop (and unregister) the view.
Admins should NOT drop a view unless they wish to also discard the entries in the analysis cache associated with that view. Instead, admins should use the dematerialize method.
User class¶
-
class
leapyear.admin.
User
(username, password=None, *, is_root=None, enabled=None, user_id=None, subj_id=None)¶ User object.
-
property
groups
¶ Get the groups of a user.
- Returns
All groups of the user on the LeapYear server.
- Return type
List[Group]
-
load
()¶ Load the information for the user.
- Return type
User
-
create
()¶ Create the user.
- Return type
User
-
update
(*, password=None, enabled=None)¶ Update the user.
- Return type
User
-
property
Privacy Profile class¶
-
class
leapyear.admin.
PrivacyProfile
(name, params=None, hidden=None, verified=None, description=None, profile_id=None)¶ PrivacyProfile object.
Get whether the profile is hidden in the Data Manager.
- Return type
-
property
params
¶ Get the parameters of the privacy profile.
- Return type
PrivacyProfileParams
-
property
identifier
¶ Get the identifier of the privacy profile.
-
load
()¶ Load the privacy profile.
-
create
()¶ Create the privacy profile.
-
update
(params=None, hidden=None)¶ Update the privacy profile’s params.
-
drop
()¶ Drop the privacy profile.
Permission objects¶
-
class
leapyear.admin.
DatabaseAccessType
(value)¶ AccessType for Databases.
-
NO_ACCESS_TO_DB
= 'NO_ACCESS_TO_DB'¶ Prevents user from accessing database
-
SHOW_DATABASE
= 'SHOW_DATABASE'¶ Allows a user to see this database and the tables it contains, including their public metadata
-
ADMINISTER_DATABASE
= 'ADMINISTER_DATABASE'¶ Allows a user to administer this database - e.g. add data sources, grant user access
-
-
class
leapyear.admin.
ColumnAccessType
(value)¶ AccessType for Columns.
-
NO_ACCESS
= 'NO_ACCESS'¶ Prevents user from accessing column
-
COMPUTE
= 'COMPUTE'¶ Allows a user to run randomized computations
-
FULL_ACCESS
= 'FULL_ACCESS'¶ Allows a user to run randomized computations and view and retrieve raw data
-
COMPARE
= 'COMPARE'¶
-