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_preprocess_csv(id)

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

post_multipart_complete(id)

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

delete_shares_groups(id: int, group_id: int)

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

delete_shares_users(id: int, user_id: int)

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_shares(id: int)

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

put_shares_groups(id: int, group_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

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.

put_shares_users(id: int, user_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

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