civis.io.file_to_civis¶

civis.io.file_to_civis(buf, name=None, api_key=None, client=None, **kwargs)[source]¶

Upload a file to Civis.

Parameters:	buf : file-like object or str The file or other buffer that you wish to upload. Strings will be treated as paths to local files to open. name : str, 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). api_key : DEPRECATED str, optional Your Civis API key. If not given, the `CIVIS_API_KEY` environment variable will be used. client : `civis.APIClient`, optional If not provided, an `civis.APIClient` object will be created from the `CIVIS_API_KEY`. **kwargs : kwargs Extra keyword arguments will be passed to the file creation endpoint. See `post()`.
Returns:	file_id : int The new Civis file ID.
Raises:	TypeError If `name` is not provided and cannot be inferred from `buf`

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

>>> # Upload file at a given path on the local filesystem.
>>> file_id = file_to_civis("my_data.csv", 'my_data')
>>> # If not given, ``name`` will be the basename of the given file path.
>>> file_id = 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 = file_to_civis(f, 'my_data')
>>> # Upload file which never expires
>>> with open("my_data.csv", "r") as f:
...     file_id = file_to_civis(f, 'my_data', expires_at=None)