Calendar file

class datarobot.CalendarFile

Represents the data for a calendar file.

For more information about calendar files, see the calendar documentation.

Variables:

id (str) – The id of the calendar file.
calendar_start_date (str) – The earliest date in the calendar.
calendar_end_date (str) – The last date in the calendar.
created (str) – The date this calendar was created, i.e. uploaded to DR.
name (str) – The name of the calendar.
num_event_types (int) – The number of different event types.
num_events (int) – The number of events this calendar has.
project_ids (list of strings) – A list containing the projectIds of the projects using this calendar.
multiseries_id_columns (List[str] or None) – A list of columns in calendar which uniquely identify events for different series. Currently, only one column is supported. If multiseries id columns are not provided, calendar is considered to be single series.
role (str) – The access role the user has for this calendar.

classmethod create(file_path, calendar_name=None, multiseries_id_columns=None)

Creates a calendar using the given file. For information about calendar files, see the calendar documentation

The provided file must be a CSV in the format:

Date,   Event,          Series ID,    Event Duration
<date>, <event_type>,   <series id>,  <event duration>
<date>, <event_type>,              ,  <event duration>

A header row is required, and the “Series ID” and “Event Duration” columns are optional.

Once the CalendarFile has been created, pass its ID with the DatetimePartitioningSpecification when setting the target for a time series project in order to use it.

Parameters:

file_path (string) – A string representing a path to a local csv file.
calendar_name (string, optional) – A name to assign to the calendar. Defaults to the name of the file if not provided.
multiseries_id_columns (List[str] or None) – A list of the names of multiseries id columns to define which series an event belongs to. Currently only one multiseries id column is supported.

Returns:

calendar_file – Instance with initialized data.

Return type:

CalendarFile

Raises:

AsyncProcessUnsuccessfulError – Raised if there was an error processing the provided calendar file.

Examples

# Creating a calendar with a specified name
cal = dr.CalendarFile.create('/home/calendars/somecalendar.csv',
                                         calendar_name='Some Calendar Name')
cal.id
>>> 5c1d4904211c0a061bc93013
cal.name
>>> Some Calendar Name

# Creating a calendar without specifying a name
cal = dr.CalendarFile.create('/home/calendars/somecalendar.csv')
cal.id
>>> 5c1d4904211c0a061bc93012
cal.name
>>> somecalendar.csv

# Creating a calendar with multiseries id columns
cal = dr.CalendarFile.create('/home/calendars/somemultiseriescalendar.csv',
                             calendar_name='Some Multiseries Calendar Name',
                             multiseries_id_columns=['series_id'])
cal.id
>>> 5da9bb21962d746f97e4daee
cal.name
>>> Some Multiseries Calendar Name
cal.multiseries_id_columns
>>> ['series_id']

classmethod create_calendar_from_dataset(dataset_id, dataset_version_id=None, calendar_name=None, multiseries_id_columns=None, delete_on_error=False)

Creates a calendar using the given dataset. For information about calendar files, see the calendar documentation

The provided dataset have the following format:

Date,   Event,          Series ID,    Event Duration
<date>, <event_type>,   <series id>,  <event duration>
<date>, <event_type>,              ,  <event duration>

The “Series ID” and “Event Duration” columns are optional.

Once the CalendarFile has been created, pass its ID with the DatetimePartitioningSpecification when setting the target for a time series project in order to use it.

Parameters:

dataset_id (string) – The identifier of the dataset from which to create the calendar.
dataset_version_id (string, optional) – The identifier of the dataset version from which to create the calendar.
calendar_name (string, optional) – A name to assign to the calendar. Defaults to the name of the dataset if not provided.
multiseries_id_columns (list of Optional[str]) – A list of the names of multiseries id columns to define which series an event belongs to. Currently only one multiseries id column is supported.
delete_on_error (boolean, optional) – Whether delete calendar file from Catalog if it’s not valid.

Returns:

calendar_file – Instance with initialized data.

Return type:

CalendarFile

Raises:

AsyncProcessUnsuccessfulError – Raised if there was an error processing the provided calendar file.

Examples

# Creating a calendar from a dataset
dataset = dr.Dataset.create_from_file('/home/calendars/somecalendar.csv')
cal = dr.CalendarFile.create_calendar_from_dataset(
    dataset.id, calendar_name='Some Calendar Name'
)
cal.id
>>> 5c1d4904211c0a061bc93013
cal.name
>>> Some Calendar Name

# Creating a calendar from a new dataset version
new_dataset_version = dr.Dataset.create_version_from_file(
    dataset.id, '/home/calendars/anothercalendar.csv'
)
cal = dr.CalendarFile.create(
    new_dataset_version.id, dataset_version_id=new_dataset_version.version_id
)
cal.id
>>> 5c1d4904211c0a061bc93012
cal.name
>>> anothercalendar.csv

classmethod create_calendar_from_country_code(country_code, start_date, end_date)

Generates a calendar based on the provided country code and dataset start date and end dates. The provided country code should be uppercase and 2-3 characters long. See CalendarFile.get_allowed_country_codes for a list of allowed country codes.

Parameters:

country_code (string) – The country code for the country to use for generating the calendar.
start_date (datetime.datetime) – The earliest date to include in the generated calendar.
end_date (datetime.datetime) – The latest date to include in the generated calendar.

Returns:

calendar_file – Instance with initialized data.

Return type:

CalendarFile

classmethod get_allowed_country_codes(offset=None, limit=None)

Retrieves the list of allowed country codes that can be used for generating the preloaded calendars.

Parameters:

offset (int) – Optional, defaults to 0. This many results will be skipped.
limit (int) – Optional, defaults to 100, maximum 1000. At most this many results are returned.

Returns:

A list dicts, each of which represents an allowed country codes. Each item has the following structure:

name : (str) The name of the country.
code : (str) The code for this country. This is the value that should be supplied to CalendarFile.create_calendar_from_country_code.

Return type:

list

classmethod get(calendar_id)

Gets the details of a calendar, given the id.

Parameters:: calendar_id (str) – The identifier of the calendar.
Returns:: calendar_file – The requested calendar.
Return type:: CalendarFile
Raises:: DataError – Raised if the calendar_id is invalid, i.e. the specified CalendarFile does not exist.

Examples

cal = dr.CalendarFile.get(some_calendar_id)
cal.id
>>> some_calendar_id

classmethod list(project_id=None, batch_size=None)

Gets the details of all calendars this user has view access for.

Parameters:

project_id (Optional[str]) – If provided, will filter for calendars associated only with the specified project.
batch_size (Optional[int]) – The number of calendars to retrieve in a single API call. If specified, the client may make multiple calls to retrieve the full list of calendars. If not specified, an appropriate default will be chosen by the server.

Returns:

calendar_list – A list of CalendarFile objects.

Return type:

list of CalendarFile

Examples

calendars = dr.CalendarFile.list()
len(calendars)
>>> 10

classmethod delete(calendar_id)

Deletes the calendar specified by calendar_id.

Parameters:: calendar_id (str) – The id of the calendar to delete. The requester must have OWNER access for this calendar.
Raises:: ClientError – Raised if an invalid calendar_id is provided.
Return type:: None

Examples

# Deleting with a valid calendar_id
status_code = dr.CalendarFile.delete(some_calendar_id)
status_code
>>> 204
dr.CalendarFile.get(some_calendar_id)
>>> ClientError: Item not found

classmethod update_name(calendar_id, new_calendar_name)

Changes the name of the specified calendar to the specified name. The requester must have at least READ_WRITE permissions on the calendar.

Parameters:

calendar_id (str) – The id of the calendar to update.
new_calendar_name (str) – The new name to set for the specified calendar.

Returns:

status_code – 200 for success

Return type:

int

Raises:

ClientError – Raised if an invalid calendar_id is provided.

Examples

response = dr.CalendarFile.update_name(some_calendar_id, some_new_name)
response
>>> 200
cal = dr.CalendarFile.get(some_calendar_id)
cal.name
>>> some_new_name

classmethod share(calendar_id, access_list)

Shares the calendar with the specified users, assigning the specified roles.

Parameters:

calendar_id (str) – The id of the calendar to update
access_list (List[SharingAccess]) – A list of dr.SharingAccess objects. Specify None for the role to delete a user’s access from the specified CalendarFile. For more information on specific access levels, see the sharing documentation.

Returns:

status_code – 200 for success

Return type:

int

Raises:

ClientError – Raised if unable to update permissions for a user.
AssertionError – Raised if access_list is invalid.

Examples

# assuming some_user is a valid user, share this calendar with some_user
sharing_list = [dr.SharingAccess(some_user_username,
                                 dr.enums.SHARING_ROLE.READ_WRITE)]
response = dr.CalendarFile.share(some_calendar_id, sharing_list)
response.status_code
>>> 200

# delete some_user from this calendar, assuming they have access of some kind already
delete_sharing_list = [dr.SharingAccess(some_user_username,
                                        None)]
response = dr.CalendarFile.share(some_calendar_id, delete_sharing_list)
response.status_code
>>> 200

# Attempt to add an invalid user to a calendar
invalid_sharing_list = [dr.SharingAccess(invalid_username,
                                         dr.enums.SHARING_ROLE.READ_WRITE)]
dr.CalendarFile.share(some_calendar_id, invalid_sharing_list)
>>> ClientError: Unable to update access for this calendar

classmethod get_access_list(calendar_id, batch_size=None)

Retrieve a list of users that have access to this calendar.

Parameters:

calendar_id (str) – The id of the calendar to retrieve the access list for.
batch_size (Optional[int]) – The number of access records to retrieve in a single API call. If specified, the client may make multiple calls to retrieve the full list of calendars. If not specified, an appropriate default will be chosen by the server.

Returns:

access_control_list – A list of SharingAccess objects.

Return type:

list of SharingAccess

Raises:

ClientError – Raised if user does not have access to calendar or calendar does not exist.

class datarobot.models.calendar_file.CountryCode