Files
- class Files(session_kwargs, client, return_type='raw')
Examples
>>> import civis >>> client = civis.APIClient() >>> client.files.list_projects(...)
Methods
delete_projects
(id, project_id)Remove a File from a project
delete_shares_groups
(id, group_id)Revoke the permissions a group has on this object
delete_shares_users
(id, user_id)Revoke the permissions a user has on this object
get
(id, *[, link_expires_at, inline])Get details about a file
Get a Preprocess CSV
list_dependencies
(id, *[, user_id])List dependent objects for this object
list_projects
(id, *[, hidden])List the projects a File belongs to
list_shares
(id)List users and groups permissioned on this object
patch
(id, *[, name, expires_at])Update details about a file
patch_preprocess_csv
(id, *[, file_id, ...])Update some attributes of this Preprocess CSV
post
(name, *[, expires_at])Initiate an upload of a file into the platform
post_multipart
(name, num_parts, *[, expires_at])Initiate a multipart upload
Complete a multipart upload
post_preprocess_csv
(file_id, *[, in_place, ...])Create a Preprocess CSV
put
(id, name, expires_at)Update details about a file
put_preprocess_csv
(id, file_id, *[, ...])Replace all attributes of this Preprocess CSV
put_preprocess_csv_archive
(id, status)Update the archive status of this object
put_projects
(id, project_id)Add a File to a project
put_shares_groups
(id, group_ids, ...[, ...])Set the permissions groups has on this object
put_shares_users
(id, user_ids, ...[, ...])Set the permissions users have on this object
put_transfer
(id, user_id, ...[, email_body, ...])Transfer ownership of this object to another user
- delete_projects(id: int, project_id: int)
Remove a File from a project
- Parameters:
- idint
The ID of the File.
- project_idint
The ID of the project.
- Returns:
- None
Response code 204: success
Revoke the permissions a group has on this object
- Parameters:
- idint
The ID of the resource that is shared.
- group_idint
The ID of the group.
- Returns:
- None
Response code 204: success
Revoke the permissions a user has on this object
- Parameters:
- idint
The ID of the resource that is shared.
- user_idint
The ID of the user.
- Returns:
- None
Response code 204: success
- get(id: int, *, link_expires_at: str = None, inline: bool = None)
Get details about a file
- Parameters:
- idint
The ID of the file.
- link_expires_atstr, optional
The date and time the download link will expire. Must be a time between now and 36 hours from now. Defaults to 30 minutes from now.
- inlinebool, optional
If true, will return a url that can be displayed inline in HTML
- Returns:
civis.response.Response
- idint
The ID of the file.
- namestr
The file name.
- created_atstr (date-time)
The date and time the file was created.
- file_sizeint
The file size.
- expires_atstr (date-time)
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- download_urlstr
A JSON string containing information about the URL of the file.
- file_urlstr
The URL that may be used to download the file.
- detected_infodict
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”.
- compressionstr
The type of compression of the file. One of “gzip”, or “none”.
- table_columnsList[dict]
An array of hashes corresponding to the columns in the file. Each hash should have keys for column “name” and “sql_type”
- namestr
The column name.
- sql_typestr
The SQL type of the column.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
- get_preprocess_csv(id: int)
Get a Preprocess CSV
- Parameters:
- idint
- Returns:
civis.response.Response
- idint
The ID of the job created.
- file_idint
The ID of the file.
- in_placebool
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- hiddenbool
The hidden status of the item.
- list_dependencies(id: int, *, user_id: int = None)
List dependent objects for this object
- Parameters:
- idint
The ID of the resource that is shared.
- user_idint, optional
ID of target user
- Returns:
civis.response.Response
- object_typestr
Dependent object type
- fco_typestr
Human readable dependent object type
- idint
Dependent object ID
- namestr
Dependent object name, or nil if the requesting user cannot read this object
- permission_levelstr
Permission level of target user (not user’s groups) for dependent object. Null if no target user or not shareable (e.g. a database table).
- descriptionstr
Additional information about the dependency, if relevant
- shareablebool
Whether or not the requesting user can share this object.
- list_projects(id: int, *, hidden: bool = None)
List the projects a File belongs to
- Parameters:
- idint
The ID of the File.
- hiddenbool, optional
If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
- Returns:
civis.response.Response
- idint
The ID for this project.
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- namestr
The name of this project.
- descriptionstr
A description of the project.
- usersList[dict]
Users who can see the project.
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
auto_share : bool
created_at : str (time)
updated_at : str (time)
- archivedstr
The archival status of the requested item(s).
List users and groups permissioned on this object
- Parameters:
- idint
The ID of the resource that is shared.
- Returns:
civis.response.Response
- readersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- writersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- ownersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
- total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
- patch(id: int, *, name: str = None, expires_at: str = None)
Update details about a file
- Parameters:
- idint
The ID of the file.
- namestr, optional
The file name. The extension must match the previous extension.
- expires_atstr (date-time), optional
The date and time the file will expire.
- Returns:
civis.response.Response
- idint
The ID of the file.
- namestr
The file name.
- created_atstr (date-time)
The date and time the file was created.
- file_sizeint
The file size.
- expires_atstr (date-time)
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- download_urlstr
A JSON string containing information about the URL of the file.
- file_urlstr
The URL that may be used to download the file.
- detected_infodict
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”.
- compressionstr
The type of compression of the file. One of “gzip”, or “none”.
- table_columnsList[dict]
An array of hashes corresponding to the columns in the file. Each hash should have keys for column “name” and “sql_type”
- namestr
The column name.
- sql_typestr
The SQL type of the column.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
- patch_preprocess_csv(id: int, *, file_id: int = None, in_place: bool = None, detect_table_columns: bool = None, force_character_set_conversion: bool = None, include_header: bool = None, column_delimiter: str = None)
Update some attributes of this Preprocess CSV
- Parameters:
- idint
The ID of the job created.
- file_idint, optional
The ID of the file.
- in_placebool, optional
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool, optional
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool, optional
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool, optional
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr, optional
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- Returns:
civis.response.Response
- idint
The ID of the job created.
- file_idint
The ID of the file.
- in_placebool
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- hiddenbool
The hidden status of the item.
- post(name: str, *, expires_at: str = None)
Initiate an upload of a file into the platform
- Parameters:
- namestr
The file name.
- expires_atstr (date-time), optional
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- Returns:
civis.response.Response
- idint
The ID of the file.
- namestr
The file name.
- created_atstr (date-time)
The date and time the file was created.
- file_sizeint
The file size.
- expires_atstr (date-time)
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- upload_urlstr
The URL that may be used to upload a file. To use the upload URL, initiate a POST request to the given URL with the file you wish to import as the “file” form field.
- upload_fieldsdict
A hash containing the form fields to be included with the POST request.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
- post_multipart(name: str, num_parts: int, *, expires_at: str = None)
Initiate a multipart upload
- Parameters:
- namestr
The file name.
- num_partsint
The number of parts in which the file will be uploaded. This parameter determines the number of presigned URLs that are returned.
- expires_atstr (date-time), optional
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- Returns:
civis.response.Response
- idint
The ID of the file.
- namestr
The file name.
- created_atstr (date-time)
The date and time the file was created.
- file_sizeint
The file size.
- expires_atstr (date-time)
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- upload_urlsList[str]
An array of URLs that may be used to upload file parts. Use separate PUT requests to complete the part uploads. Links expire after 12 hours.
- post_multipart_complete(id: int)
Complete a multipart upload
- Parameters:
- idint
The ID of the file.
- Returns:
- None
Response code 204: success
- post_preprocess_csv(file_id: int, *, in_place: bool = None, detect_table_columns: bool = None, force_character_set_conversion: bool = None, include_header: bool = None, column_delimiter: str = None, hidden: bool = None)
Create a Preprocess CSV
- Parameters:
- file_idint
The ID of the file.
- in_placebool, optional
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool, optional
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool, optional
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool, optional
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr, optional
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- hiddenbool, optional
The hidden status of the item.
- Returns:
civis.response.Response
- idint
The ID of the job created.
- file_idint
The ID of the file.
- in_placebool
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- hiddenbool
The hidden status of the item.
- put(id: int, name: str, expires_at: str)
Update details about a file
- Parameters:
- idint
The ID of the file.
- namestr
The file name. The extension must match the previous extension.
- expires_atstr (date-time)
The date and time the file will expire.
- Returns:
civis.response.Response
- idint
The ID of the file.
- namestr
The file name.
- created_atstr (date-time)
The date and time the file was created.
- file_sizeint
The file size.
- expires_atstr (date-time)
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- download_urlstr
A JSON string containing information about the URL of the file.
- file_urlstr
The URL that may be used to download the file.
- detected_infodict
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”.
- compressionstr
The type of compression of the file. One of “gzip”, or “none”.
- table_columnsList[dict]
An array of hashes corresponding to the columns in the file. Each hash should have keys for column “name” and “sql_type”
- namestr
The column name.
- sql_typestr
The SQL type of the column.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
- put_preprocess_csv(id: int, file_id: int, *, in_place: bool = None, detect_table_columns: bool = None, force_character_set_conversion: bool = None, include_header: bool = None, column_delimiter: str = None)
Replace all attributes of this Preprocess CSV
- Parameters:
- idint
The ID of the job created.
- file_idint
The ID of the file.
- in_placebool, optional
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool, optional
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool, optional
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool, optional
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr, optional
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- Returns:
civis.response.Response
- idint
The ID of the job created.
- file_idint
The ID of the file.
- in_placebool
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- hiddenbool
The hidden status of the item.
- put_preprocess_csv_archive(id: int, status: bool)
Update the archive status of this object
- Parameters:
- idint
The ID of the object.
- statusbool
The desired archived status of the object.
- Returns:
civis.response.Response
- idint
The ID of the job created.
- file_idint
The ID of the file.
- in_placebool
If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
- detect_table_columnsbool
If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
- force_character_set_conversionbool
If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
- include_headerbool
A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
- column_delimiterstr
The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
- hiddenbool
The hidden status of the item.
- put_projects(id: int, project_id: int)
Add a File to a project
- Parameters:
- idint
The ID of the File.
- project_idint
The ID of the project.
- Returns:
- None
Response code 204: success
Set the permissions groups has on this object
- Parameters:
- idint
The ID of the resource that is shared.
- group_idsList[int]
An array of one or more group IDs.
- permission_levelstr
Options are: “read”, “write”, or “manage”.
- share_email_bodystr, optional
Custom body text for e-mail sent on a share.
- send_shared_emailbool, optional
Send email to the recipients of a share.
- Returns:
civis.response.Response
- readersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- writersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- ownersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
- total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
- Parameters:
- idint
The ID of the resource that is shared.
- user_idsList[int]
An array of one or more user IDs.
- permission_levelstr
Options are: “read”, “write”, or “manage”.
- share_email_bodystr, optional
Custom body text for e-mail sent on a share.
- send_shared_emailbool, optional
Send email to the recipients of a share.
- Returns:
civis.response.Response
- readersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- writersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- ownersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
- total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
- put_transfer(id: int, user_id: int, include_dependencies: bool, *, email_body: str = None, send_email: bool = None)
Transfer ownership of this object to another user
- Parameters:
- idint
The ID of the resource that is shared.
- user_idint
ID of target user
- include_dependenciesbool
Whether or not to give manage permissions on all dependencies
- email_bodystr, optional
Custom body text for e-mail sent on transfer.
- send_emailbool, optional
Send email to the target user of the transfer?
- Returns:
civis.response.Response
- dependenciesList[dict]
Dependent objects for this object
- object_typestr
Dependent object type
- fco_typestr
Human readable dependent object type
- idint
Dependent object ID
- namestr
Dependent object name, or nil if the requesting user cannot read this object
- permission_levelstr
Permission level of target user (not user’s groups) for dependent object. Null if no target user or not shareable (e.g. a database table).
- descriptionstr
Additional information about the dependency, if relevant
- sharedbool
Whether dependent object was successfully shared with target user