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

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).
api_keyDEPRECATED str, optional: Your Civis API key. If not given, the CIVIS_API_KEY environment variable will be used.
clientcivis.APIClient, optional: If not provided, an civis.APIClient object will be created from the CIVIS_API_KEY.
**kwargskwargs: Extra keyword arguments will be passed to the file creation endpoint. See post(). In particular, expires_at can be specified for the date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify None. To specify a date and time, format it by the ISO 8601 standard, e.g., "2020-12-31", "2020-12-31T23:03:40Z", and what the isoformat() method returns from a datetime.date or datetime.datetime object.

Returns

file_idint: 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)