civis.io.file_to_civis

civis.io.file_to_civis(buf, name=None, expires_at='DEFAULT', description=None, client=None)[source]

Upload a file to Civis.

Parameters:

buffile-like object or str: Either a file-like object for a buffer or a string for a local file path. Note that if a file-like object is provided and it’s not an io.BufferedReader or io.TextIoWrapper object, the current implementation requires extra disk space (which could be an issue if your file is large).
namestr, optional: The name you wish to give the file. If not given, it will be inferred from the basename of buf (if buf is a string for a file path) or buf.name (if buf is a file-like object).
expires_atstr, optional: The date and time the file will expire. If not specified, the file will expire in 30 days. To specify a date and time, format it by the ISO 8601 standard (e.g., "2020-12-31", "2020-12-31T23:03:40Z"), or equivalently, the returned value of the isoformat() method from a datetime.date or datetime.datetime object. To keep a file indefinitely, specify None.
descriptionstr, optional: Description (max length: 512 characters) of the file object.
clientcivis.APIClient, optional: If not provided, an civis.APIClient object will be created from the CIVIS_API_KEY.

Returns:

file_idint: The new Civis file ID.

Raises:

TypeError: If name is not provided and cannot be inferred from buf
ValueError: If description is provided and it’s longer than 512 characters.

Notes

If you are opening a binary file (e.g., a compressed archive) to pass to this function, do so using the 'rb' (read binary) mode (e.g., open('myfile.zip', 'rb')).

Warning: If the file-like object is seekable, the current position will be reset to 0.

This facilitates retries and is used to chunk files for multipart uploads for improved performance.

Small or non-seekable file-like objects will be uploaded with a single post.

Examples

>>> import civis
>>> # Upload file at a given path on the local filesystem.
>>> file_id = civis.io.file_to_civis("my_data.csv", 'my_data')
>>> # If not given, ``name`` will be the basename of the given file path.
>>> file_id = civis.io.file_to_civis("foo/bar/data.csv")  # ``name`` is 'data.csv'
>>> # Upload file which expires in 30 days
>>> with open("my_data.csv", "r") as f:
...     file_id = civis.io.file_to_civis(f, 'my_data')
>>> # Upload file which never expires
>>> with open("my_data.csv", "r") as f:
...     file_id = civis.io.file_to_civis(f, 'my_data', expires_at=None)