civis.io.file_to_civis

civis.io.file_to_civis(buf: BinaryIO | str | bytes | PathLike, name: str | None = None, expires_at: str | None = 'DEFAULT', description: str | None = None, client: APIClient | None = None) → int[source]

Upload a file to Civis.

Parameters:
buffile-like object or path-like object

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)