a |f>@sdZddlmZddlmZmZmZmZmZm Z ddl m Z ddl m Z mZddlmZmZddlmZmZmZdd lmZdd lmZmZdd lmZmZmZmZGd d d Z dS)zn gspread.client ~~~~~~~~~~~~~~ This module contains Client class responsible for managing spreadsheet files ) HTTPStatus)AnyDictListOptionalTupleUnion) Credentials)ResponseSession)APIErrorSpreadsheetNotFound) HTTPClientHTTPClientType ParamsType) Spreadsheet)DRIVE_FILES_API_V3_COMMENTS_URLDRIVE_FILES_API_V3_URL) ExportFormatMimeTypeextract_id_from_urlfinditemc @seZdZdZdefeeeeddddZ d4ee e e e e ffddddZ eed d d Zd5eeeeeeeefd d dZd6eeeee eeeefefd ddZd7eeeed ddZeedddZeedddZd8eeeedddZd9eeeed ddZejfeeeddd Zd:eeee eee ed#d$d%Z!edd&d'd(Z"ee eefed)d*d+Z#eeeee ee ffd&d,d-Z$d;eeeeeeee eee ed.d/d0Z%eedd1d2d3Z&dS)<Clienta7An instance of this class Manages Spreadsheet files It is used to: - open/create/list/delete spreadsheets - create/delete/list spreadsheet permission - etc It is the gspread entry point. It will handle creating necessary :class:`~gspread.models.Spreadsheet` instances. N)authsession http_clientreturncCs||||_dS)N)r)selfrrrrHD:\Projects\storyit_web\backend\venv\Lib\site-packages\gspread/client.py__init__"szClient.__init__)timeoutrcCs|j|dS)zHow long to wait for the server to send data before giving up, as a float, or a ``(connect timeout, read timeout)`` tuple. Use value ``None`` to restore default timeout Value for ``timeout`` is in seconds (s). N)r set_timeout)rr"rrr r#*s zClient.set_timeout)idrcCs |j|S)zGet the metadata from the Drive API for a specific file This method is mainly here to retrieve the create/update time of a file (these metadata are only accessible from the Drive API). )rget_file_drive_metadata)rr$rrr r%7szClient.get_file_drive_metadata)title folder_idrcCs|j||d\}}|S)a:List all the spreadsheet files Will list all spreadsheet files owned by/shared with this user account. :param str title: Filter only spreadsheet files with this title :param str folder_id: Only look for spreadsheet files in this folder The parameter ``folder_id`` can be obtained from the URL when looking at a folder in a web browser as follow: ``https://drive.google.com/drive/u/0/folders/`` :returns: a list of dicts containing the keys id, name, createdTime and modifiedTime. )r&r')_list_spreadsheet_files)rr&r'files_rrr list_spreadsheet_files>szClient.list_spreadsheet_filesc Csg}d}t}dtjd}|r.|d|d7}|rB|d|d7}|ddddd }|r^||d <|jjd ||d }|} || d | dd}|durRqqR||fS)Nz mimeType=""z and name = "z and parents in "iTz:kind,nextPageToken,files(id,name,createdTime,modifiedTime))qpageSizesupportsAllDrivesZincludeItemsFromAllDrivesfields pageTokengetparamsr) nextPageToken)rr google_sheetsrrequestjsonextendr3) rr&r'r) page_tokenurlqueryr5responseZ response_jsonrrr r(Ps.  zClient._list_spreadsheet_filesc sn||\}}ztfdd|}Wn.tyT}zt||WYd}~n d}~00|d|d<t|j|S)a.Opens a spreadsheet. :param str title: A title of a spreadsheet. :param str folder_id: (optional) If specified can be used to filter spreadsheets by parent folder ID. :returns: a :class:`~gspread.models.Spreadsheet` instance. If there's more than one spreadsheet with same title the first one will be opened. :raises gspread.SpreadsheetNotFound: if no spreadsheet with specified `title` is found. >>> gc.open('My fancy spreadsheet') cs |dkS)Nnamer)xr&rr zClient.open..Nr?r&)r(r StopIterationrrr)rr&r'spreadsheet_filesr> propertiesexrrAr opents   z Client.open)keyrc Cspzt|jd|i}WnVtyj}z>|jjtjkr>t|j||jjtjkrRt ||WYd}~n d}~00|S)a+Opens a spreadsheet specified by `key` (a.k.a Spreadsheet ID). :param str key: A key of a spreadsheet as it appears in a URL in a browser. :returns: a :class:`~gspread.models.Spreadsheet` instance. >>> gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE') r$N) rrr r> status_coder NOT_FOUNDr FORBIDDENPermissionError)rrI spreadsheetrGrrr open_by_keys zClient.open_by_key)r<rcCs|t|S)aOpens a spreadsheet specified by `url`. :param str url: URL of a spreadsheet as it appears in a browser. :returns: a :class:`~gspread.models.Spreadsheet` instance. :raises gspread.SpreadsheetNotFound: if no spreadsheet with specified `url` is found. >>> gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl') )rOr)rr<rrr open_by_urls zClient.open_by_url)r&rcs2}r fdd|D}fdd|DS)zOpens all available spreadsheets. :param str title: (optional) If specified can be used to filter spreadsheets by title. :returns: a list of :class:`~gspread.models.Spreadsheet` instances. csg|]}|dkr|qS)r?r).0ZspreadrArr sz"Client.openall..c s*g|]"}tjtfd|di|qS)r&r?)rrdict)rQr@)rrr rRs)r+)rr&rEr)rr&r openalls   zClient.openallcCsP|tjd}ddi}|dur&|g|d<|jjdt||d}|d}||S) aCreates a new spreadsheet. :param str title: A title of a new spreadsheet. :param str folder_id: Id of the folder where we want to save the spreadsheet. :returns: a :class:`~gspread.models.Spreadsheet` instance. r?ZmimeTyper0TNparentspostr9r5r$)rr7rr8rr9rO)rr&r'payloadr5rspreadsheet_idrrr creates   z Client.create)file_idformatrcCs|jj||dS)aExport the spreadsheet in the given format. :param str file_id: The key of the spreadsheet to export :param str format: The format of the resulting file. Possible values are: * ``ExportFormat.PDF`` * ``ExportFormat.EXCEL`` * ``ExportFormat.CSV`` * ``ExportFormat.OPEN_OFFICE_SHEET`` * ``ExportFormat.TSV`` * ``ExportFormat.ZIPPED_HTML`` See `ExportFormat`_ in the Drive API. :type format: :class:`~gspread.utils.ExportFormat` :returns bytes: The content of the exported file. .. _ExportFormat: https://developers.google.com/drive/api/guides/ref-export-formats )r]r^)rexport)rr]r^rrr r_sz Client.exportFT)r]r&copy_permissionsr' copy_commentsrcCsdt|}|tjd}|dur*|g|d<ddi}|jjd|||d} | d } || } |dur||} | } | D]p}| d rqzd }t |d d krt |d }nt |d dvrt |d}| j |t |d t |dddqz|durt |}d }g}dddd}|durX||d<|jjd||d}| |d| dd}qt | j}dd i}|D]}|jjd|||dqn| S)aCopies a spreadsheet. :param str file_id: A key of a spreadsheet to copy. :param str title: (optional) A title for the new spreadsheet. :param bool copy_permissions: (optional) If True, copy permissions from the original spreadsheet to the new spreadsheet. :param str folder_id: Id of the folder where we want to save the spreadsheet. :param bool copy_comments: (optional) If True, copy the comments from the original spreadsheet to the new spreadsheet. :returns: a :class:`~gspread.models.Spreadsheet` instance. .. versionadded:: 3.1.0 .. note:: If you're using custom credentials without the Drive scope, you need to add ``https://www.googleapis.com/auth/drive`` to your OAuth scope in order to use this method. Example:: scope = [ 'https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive' ] Otherwise, you will get an ``Insufficient Permission`` error when you try to copy a spreadsheet. z {}/{}/copyrUNrVr0TrWrXr$Zdeletedr,typedomain)usergroupZ emailAddressroleF)Z email_address perm_typerfnotifyz.comments/content,comments/anchor,nextPageTokend)r1ZincludeDeletedr/r2r3r4commentsr6r1)r^rrr7rr8r9rOlist_permissionsr3strsharerr:r$)rr]r&r`r'rar<rYr5rZr[Znew_spreadsheetoriginalZ permissionspZemail_or_domain source_urlr;rjresZdestination_urlcommentrrr copys^+             z Client.copy)r]rcCs*dt|}ddi}|jjd||ddS)z^Deletes a spreadsheet. :param str file_id: a spreadsheet ID (a.k.a file ID). z{}/{}r0Tdeleter4N)r^rrr8)rr]r<r5rrr del_spreadsheetms zClient.del_spreadsheet)r]datarcCs|j||S)aImports data into the first page of the spreadsheet. :param str file_id: :param str data: A CSV string of data. Example: .. code:: # Read CSV file contents content = open('file_to_import.csv', 'r').read() gc.import_csv(spreadsheet.id, content) .. note:: This method removes all other worksheets and then entirely replaces the contents of the first worksheet. )r import_csv)rr]rvrrr rwwszClient.import_csvcCs |j|S)zpRetrieve a list of permissions for a file. :param str file_id: a spreadsheet ID (aka file ID). )rrk)rr]rrr rkszClient.list_permissions)r]valuergrfrh email_message with_linkrc Cs|j|||||||S)apCreates a new permission for a file. :param str file_id: a spreadsheet ID (aka file ID). :param value: user or group e-mail address, domain name or None for 'anyone' type. :type value: str, None :param str perm_type: (optional) The account type. Allowed values are: ``user``, ``group``, ``domain``, ``anyone`` :param str role: (optional) The primary role for this user. Allowed values are: ``owner``, ``writer``, ``reader`` :param bool notify: (optional) Whether to send an email to the target user/domain. :param str email_message: (optional) An email message to be sent if ``notify=True``. :param bool with_link: (optional) Whether the link is required for this permission to be active. :returns dict: the newly created permission Examples:: # Give write permissions to otto@example.com gc.insert_permission( '0BmgG6nO_6dprnRRUWl1UFE', 'otto@example.org', perm_type='user', role='writer' ) # Make the spreadsheet publicly readable gc.insert_permission( '0BmgG6nO_6dprnRRUWl1UFE', None, perm_type='anyone', role='reader' ) )rinsert_permission)rr]rxrgrfrhryrzrrr r{s2zClient.insert_permission)r] permission_idrcCs|j||dS)zDeletes a permission from a file. :param str file_id: a spreadsheet ID (aka file ID.) :param str permission_id: an ID for the permission. N)rremove_permission)rr]r|rrr r}szClient.remove_permission)N)NN)NN)N)N)N)NFNT)NNNTNF)'__name__ __module__ __qualname____doc__rr rr rr!rfloatrr#rlrr%rrr+r r(rrHrOrPrTr\rZPDFbytesr_boolrsrurwrkr{r}rrrr rs~      $ p $  6rN)!rhttprtypingrrrrrrZgoogle.auth.credentialsr requestsr r exceptionsr rrrrrrNrurlsrrutilsrrrrrrrrr s