GData.DocumentsService¶
- Subclasses:
None
Methods¶
- Inherited:
GData.Service (27), GObject.Object (37), GData.Batchable (1)
- Structs:
class |
|
class |
|
class |
|
class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
Properties¶
- Inherited:
Signals¶
- Inherited:
Fields¶
- Inherited:
Name |
Type |
Access |
Description |
---|---|---|---|
parent |
r |
Class Details¶
- class GData.DocumentsService(**kwargs)¶
- Bases:
- Abstract:
No
- Structure:
All the fields in the
GData.DocumentsService
structure are private and should never be accessed directly.New in version 0.4.0.
- classmethod get_primary_authorization_domain()¶
- Returns:
the service’s authorization domain
- Return type:
The primary
GData.AuthorizationDomain
for interacting with Google Documents. This will not normally need to be used, as it’s used internally by theGData.DocumentsService
methods. However, if using the plainGData.Service
methods to implement custom queries or requests which libgdata does not support natively, then this domain may be needed to authorize the requests.The domain never changes, and is interned so that pointer comparison can be used to differentiate it from other authorization domains.
New in version 0.9.0.
- classmethod get_spreadsheet_authorization_domain()¶
- Returns:
the service’s authorization domain
- Return type:
The
GData.AuthorizationDomain
for interacting with spreadsheet data. This will not normally need to be used, as it’s automatically used internally by theGData.DocumentsService
methods. However, if using the plainGData.Service
methods to implement custom queries or requests which libgdata does not support natively, then this domain may be needed to authorize the requests which pertain to the Google Spreadsheets Data API, such as requests to download or upload spreadsheet documents.The domain never changes, and is interned so that pointer comparison can be used to differentiate it from other authorization domains.
New in version 0.9.0.
- classmethod get_upload_uri(folder)¶
- Parameters:
folder (
GData.DocumentsFolder
orNone
) – theGData.DocumentsFolder
into which to upload the document, orNone
- Returns:
the URI permitting the upload of documents to folder, or
None
; free withGLib.free
()- Return type:
Gets the upload URI for documents for the service.
If folder is
None
, the URI will be the one to upload documents to the “root” folder.New in version 0.5.0.
- classmethod new(authorizer)¶
- Parameters:
authorizer (
GData.Authorizer
orNone
) – aGData.Authorizer
to authorize the service’s requests, orNone
- Returns:
a new
GData.DocumentsService
, orNone
; unref withGObject.Object.unref
()- Return type:
Creates a new
GData.DocumentsService
using the givenGData.Authorizer
. If authorizer isNone
, all requests are made as an unauthenticated user.New in version 0.9.0.
- add_entry_to_folder(entry, folder, cancellable)¶
- Parameters:
entry (
GData.DocumentsEntry
) – theGData.DocumentsEntry
to copyfolder (
GData.DocumentsFolder
) – theGData.DocumentsFolder
to copy entry intocancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
- Raises:
- Returns:
an updated
GData.DocumentsEntry
, orNone
; unref withGObject.Object.unref
()- Return type:
Add the given entry to the specified folder, and return an updated
GData.DocumentsEntry
for entry. If the entry is already in another folder, a copy will be added to the new folder. The copy and original will have different IDs. Note that entry can’t be aGData.DocumentsFolder
that already exists on the server. It can be a newGData.DocumentsFolder
, or aGData.DocumentsDocument
that is either new or already present on the server.Errors from
GData.ServiceError
can be returned for exceptional conditions, as determined by the server.New in version 0.8.0.
- add_entry_to_folder_async(entry, folder, cancellable, callback, *user_data)¶
- Parameters:
entry (
GData.DocumentsEntry
) – theGData.DocumentsEntry
to add to folderfolder (
GData.DocumentsFolder
) – theGData.DocumentsFolder
to add entry tocancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
callback (
Gio.AsyncReadyCallback
orNone
) – aGio.AsyncReadyCallback
to call when the operation is finished, orNone
user_data (
object
orNone
) – data to pass to the callback function
Add the given entry to the specified folder. self, entry and folder are all reffed when this function is called, so can safely be unreffed after this function returns.
For more details, see
GData.DocumentsService.add_entry_to_folder
(), which is the synchronous version of this function.When the operation is finished, callback will be called. You can then call
GData.DocumentsService.add_entry_to_folder_finish
() to get the results of the operation.New in version 0.8.0.
- add_entry_to_folder_finish(async_result)¶
- Parameters:
async_result (
Gio.AsyncResult
) – aGio.AsyncResult
- Raises:
- Returns:
an updated
GData.DocumentsEntry
, orNone
; unref withGObject.Object.unref
()- Return type:
Finish an asynchronous operation to add a
GData.DocumentsEntry
to a folder started withGData.DocumentsService.add_entry_to_folder_async
().New in version 0.8.0.
- copy_document(document, cancellable)¶
- Parameters:
document (
GData.DocumentsDocument
) – theGData.DocumentsDocument
to copycancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
- Raises:
- Returns:
the duplicate
GData.DocumentsDocument
, orNone
; unref withGObject.Object.unref
()- Return type:
Copy the given document, producing a duplicate document in the same folder and returning its
GData.DocumentsDocument
.Errors from
GData.ServiceError
can be returned for exceptional conditions, as determined by the server.New in version 0.13.1.
- copy_document_async(document, cancellable, callback, *user_data)¶
- Parameters:
document (
GData.DocumentsDocument
) – theGData.DocumentsDocument
to copycancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
callback (
Gio.AsyncReadyCallback
orNone
) – aGio.AsyncReadyCallback
to call when the operation is finished, orNone
user_data (
object
orNone
) – data to pass to the callback function
Copy the given document, producing a duplicate document in the same folder and returning its
GData.DocumentsDocument
. self and document are both reffed when this function is called, so can safely be unreffed after this function returns.For more details, see
GData.DocumentsService.copy_document
(), which is the synchronous version of this function.When the operation is finished, callback will be called. You can then call
GData.DocumentsService.copy_document_finish
() to get the results of the operation.New in version 0.13.1.
- copy_document_finish(async_result)¶
- Parameters:
async_result (
Gio.AsyncResult
) – aGio.AsyncResult
- Raises:
- Returns:
the duplicate
GData.DocumentsDocument
, orNone
; unref withGObject.Object.unref
()- Return type:
Finish an asynchronous operation to copy a
GData.DocumentsDocument
started withGData.DocumentsService.copy_document_async
().New in version 0.13.1.
- finish_upload(upload_stream)¶
- Parameters:
upload_stream (
GData.UploadStream
) – theGData.UploadStream
from the operation- Raises:
- Returns:
the new or updated
GData.DocumentsDocument
, orNone
; unref withGObject.Object.unref
()- Return type:
Finish off a document upload or update operation started by
GData.DocumentsService.upload_document
() orGData.DocumentsService.update_document
(), parsing the result and returning the new or updatedGData.DocumentsDocument
.If an error occurred during the upload or update operation, it will have been returned during the operation (e.g. by
Gio.OutputStream.splice
() or one of the other stream methods). In such a case,None
will be returned but error will remain unset. error is only set in the case that the server indicates that the operation was successful, but an error is encountered in parsing the result sent by the server.In the case that no
GData.DocumentsDocument
was passed (toGData.DocumentsService.upload_document
() orGData.DocumentsService.update_document
()) when starting the operation,GData.DocumentsServiceError.TYPE
will be thrown in error if the content type of the uploaded data could not be mapped to a document type with which to interpret the response from the server.New in version 0.8.0.
- get_metadata(cancellable)¶
- Parameters:
cancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
- Raises:
- Returns:
the service’s metadata object; unref with
GObject.Object.unref
()- Return type:
Gets a
GData.DocumentsMetadata
object containing metadata about the documents service itself, like how large the user quota is.New in version 0.17.9.
- get_metadata_async(cancellable, callback, *user_data)¶
- Parameters:
cancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
callback (
Gio.AsyncReadyCallback
orNone
) – aGio.AsyncReadyCallback
to call when the operation is finished, orNone
user_data (
object
orNone
) – data to pass to the callback function
Gets a
GData.DocumentsMetadata
object containing metadata about the documents service itself, like how large the user quota is.For more details, see
GData.DocumentsService.get_metadata
(), which is the synchronous version of this function.When the operation is finished, callback will be called. You can then call
GData.DocumentsService.get_metadata_finish
() to get the results of the operation.New in version 0.17.9.
- get_metadata_finish(async_result)¶
- Parameters:
async_result (
Gio.AsyncResult
) – aGio.AsyncResult
- Raises:
- Returns:
the service’s metadata object; unref with
GObject.Object.unref
()- Return type:
Finish an asynchronous operation to get a
GData.DocumentsMetadata
started withGData.DocumentsService.get_metadata_async
().New in version 0.17.9.
- query_documents(query, cancellable, progress_callback, *progress_user_data)¶
- Parameters:
query (
GData.DocumentsQuery
orNone
) – aGData.DocumentsQuery
with the query parameters, orNone
cancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
progress_callback (
GData.QueryProgressCallback
orNone
) – aGData.QueryProgressCallback
to call when an entry is loaded, orNone
progress_user_data (
object
orNone
) – data to pass to the progress_callback function
- Raises:
- Returns:
a
GData.DocumentsFeed
of query results; unref withGObject.Object.unref
()- Return type:
Queries the service to return a list of documents matching the given query. Note that query has to be a
GData.DocumentsQuery
, rather than just aGData.Query
, as it uses the folder ID specified inGData.DocumentsQuery
:folder-id
.For more details, see
GData.Service.query
().New in version 0.4.0.
- query_documents_async(query, cancellable, progress_callback, progress_user_data, callback, *user_data)¶
- Parameters:
query (
GData.DocumentsQuery
orNone
) – aGData.DocumentsQuery
with the query parameters, orNone
cancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
progress_callback (
GData.QueryProgressCallback
orNone
) – aGData.QueryProgressCallback
to call when an entry is loaded, orNone
progress_user_data (
object
orNone
) – data to pass to the progress_callback functioncallback (
Gio.AsyncReadyCallback
orNone
) – aGio.AsyncReadyCallback
to call when authentication is finisheduser_data (
object
orNone
) – data to pass to the callback function
Queries the service to return a list of documents matching the given query. self and query are both reffed when this function is called, so can safely be unreffed after this function returns.
For more details, see
GData.DocumentsService.query_documents
(), which is the synchronous version of this function, andGData.Service.query_async
(), which is the base asynchronous query function.New in version 0.9.1.
- query_drives(query, cancellable, progress_callback, *progress_user_data)¶
- Parameters:
query (
GData.DocumentsDriveQuery
orNone
) – aGData.DocumentsDriveQuery
with the query parameters, orNone
cancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
progress_callback (
GData.QueryProgressCallback
orNone
) – aGData.QueryProgressCallback
to call when an entry is loaded, orNone
progress_user_data (
object
orNone
) – data to pass to the progress_callback function
- Raises:
- Returns:
a
GData.DocumentsFeed
of query results; unref withGObject.Object.unref
()- Return type:
Queries the service to return a list of shared drives matching the given query.
For more details, see
GData.Service.query
().New in version 0.18.0.
- query_drives_async(query, cancellable, progress_callback, progress_user_data, callback, *user_data)¶
- Parameters:
query (
GData.DocumentsDriveQuery
orNone
) – aGData.DocumentsDriveQuery
with the query parameters, orNone
cancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
progress_callback (
GData.QueryProgressCallback
orNone
) – aGData.QueryProgressCallback
to call when an entry is loaded, orNone
progress_user_data (
object
orNone
) – data to pass to the progress_callback functioncallback (
Gio.AsyncReadyCallback
orNone
) – aGio.AsyncReadyCallback
to call when authentication is finisheduser_data (
object
orNone
) – data to pass to the callback function
Queries the service to return a list of shared drives matching the given query. self and query are both reffed when this function is called, so can safely be unreffed after this function returns.
For more details, see
GData.DocumentsService.query_drives
(), which is the synchronous version of this function, andGData.Service.query_async
(), which is the base asynchronous query function.New in version 0.18.0.
- remove_entry_from_folder(entry, folder, cancellable)¶
- Parameters:
entry (
GData.DocumentsEntry
) – theGData.DocumentsEntry
to removefolder (
GData.DocumentsFolder
) – theGData.DocumentsFolder
from which we should remove entrycancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
- Raises:
- Returns:
an updated
GData.DocumentsEntry
, orNone
; unref withGObject.Object.unref
()- Return type:
Remove the given entry from folder, and return an updated
GData.DocumentsEntry
for entry. entry will remain a member of any other folders it’s currently in. Note that entry can be either aGData.DocumentsDocument
or aGData.DocumentsFolder
.Errors from
GData.ServiceError
can be returned for exceptional conditions, as determined by the server.New in version 0.8.0.
- remove_entry_from_folder_async(entry, folder, cancellable, callback, *user_data)¶
- Parameters:
entry (
GData.DocumentsEntry
) – theGData.DocumentsEntry
to remove from folderfolder (
GData.DocumentsFolder
) – theGData.DocumentsFolder
to remove entry fromcancellable (
Gio.Cancellable
orNone
) – optionalGio.Cancellable
object, orNone
callback (
Gio.AsyncReadyCallback
orNone
) – aGio.AsyncReadyCallback
to call when the operation is finished, orNone
user_data (
object
orNone
) – data to pass to the callback function
Remove the given entry from the specified folder. self, entry and folder are all reffed when this function is called, so can safely be unreffed after this function returns.
For more details, see
GData.DocumentsService.remove_entry_from_folder
(), which is the synchronous version of this function.When the operation is finished, callback will be called. You can then call
GData.DocumentsService.remove_entry_from_folder_finish
() to get the results of the operation.New in version 0.8.0.
- remove_entry_from_folder_finish(async_result)¶
- Parameters:
async_result (
Gio.AsyncResult
) – aGio.AsyncResult
- Raises:
- Returns:
an updated
GData.DocumentsEntry
, orNone
; unref withGObject.Object.unref
()- Return type:
Finish an asynchronous operation to remove a
GData.DocumentsEntry
from a folder started withGData.DocumentsService.remove_entry_from_folder_async
().New in version 0.8.0.
- update_document(document, slug, content_type, cancellable)¶
- Parameters:
document (
GData.DocumentsDocument
) – theGData.DocumentsDocument
to updateslug (
str
) – the filename to give to the uploaded documentcontent_type (
str
) – the content type of the uploaded datacancellable (
Gio.Cancellable
orNone
) – aGio.Cancellable
for the entire upload stream, orNone
- Raises:
- Returns:
a
GData.UploadStream
to write the document data to; unref withGObject.Object.unref
()- Return type:
Update the document using the properties from document and the document data written to the resulting
GData.UploadStream
. If the document data does not need to be changed, just the metadata, useGData.Service.update_entry
() instead.This performs a non-resumable upload, unlike
GData.DocumentsService.update_document
(). This means that errors during transmission will cause the upload to fail, and the entire document will have to be re-uploaded. It is recommended thatGData.DocumentsService.update_document_resumable
() be used instead.The stream returned by this function should be written to using the standard
Gio.OutputStream
methods, asynchronously or synchronously. Once the stream is closed (usingGio.OutputStream.close
()),GData.DocumentsService.finish_upload
() should be called on it to parse and return the updatedGData.DocumentsDocument
for the document. This must be done, as document isn’t updated in-place.In order to cancel the update, a
Gio.Cancellable
passed in to cancellable must be cancelled usingGio.Cancellable.cancel
(). Cancelling the individualGio.OutputStream
operations on theGData.UploadStream
will not cancel the entire update; merely the write or close operation in question. See theGData.UploadStream
:cancellable
for more details.Any upload errors will be thrown by the stream methods, and may come from the
GData.ServiceError
domain.For more information, see
GData.Service.update_entry
().New in version 0.8.0.
- update_document_resumable(document, slug, content_type, content_length, cancellable)¶
- Parameters:
document (
GData.DocumentsDocument
) – theGData.DocumentsDocument
to updateslug (
str
) – the filename to give to the uploaded documentcontent_type (
str
) – the content type of the uploaded datacontent_length (
int
) – the size (in bytes) of the file being uploadedcancellable (
Gio.Cancellable
orNone
) – aGio.Cancellable
for the entire upload stream, orNone
- Raises:
- Returns:
a
GData.UploadStream
to write the document data to; unref withGObject.Object.unref
()- Return type:
Update the document using the properties from document and the document data written to the resulting
GData.UploadStream
. If the document data does not need to be changed, just the metadata, useGData.Service.update_entry
() instead.Unlike
GData.DocumentsService.update_document
(), this method performs aresumable upload which allows for correction of transmission errors without re-uploading the entire file. Use of this method is preferred over
GData.DocumentsService.update_document
().The stream returned by this function should be written to using the standard
Gio.OutputStream
methods, asynchronously or synchronously. Once the stream is closed (usingGio.OutputStream.close
()),GData.DocumentsService.finish_upload
() should be called on it to parse and return the updatedGData.DocumentsDocument
for the document. This must be done, as document isn’t updated in-place.In order to cancel the update, a
Gio.Cancellable
passed in to cancellable must be cancelled usingGio.Cancellable.cancel
(). Cancelling the individualGio.OutputStream
operations on theGData.UploadStream
will not cancel the entire update; merely the write or close operation in question. See theGData.UploadStream
:cancellable
for more details.Any upload errors will be thrown by the stream methods, and may come from the
GData.ServiceError
domain.For more information, see
GData.Service.update_entry
().New in version 0.13.0.
- upload_document(document, slug, content_type, folder, cancellable)¶
- Parameters:
document (
GData.DocumentsDocument
orNone
) – theGData.DocumentsDocument
to insert, orNone
slug (
str
) – the filename to give to the uploaded documentcontent_type (
str
) – the content type of the uploaded datafolder (
GData.DocumentsFolder
orNone
) – the folder to which the document should be uploaded, orNone
cancellable (
Gio.Cancellable
orNone
) – aGio.Cancellable
for the entire upload stream, orNone
- Raises:
- Returns:
a
GData.UploadStream
to write the document data to, orNone
; unref withGObject.Object.unref
()- Return type:
Uploads a document to Google Documents, using the properties from document and the document data written to the resulting
GData.UploadStream
. If the document data does not need to be provided at the moment, just the metadata, useGData.Service.insert_entry
() instead (e.g. in the case of creating a new, empty file to be edited at a later date).This performs a non-resumable upload, unlike
GData.DocumentsService.upload_document
(). This means that errors during transmission will cause the upload to fail, and the entire document will have to be re-uploaded. It is recommended thatGData.DocumentsService.upload_document_resumable
() be used instead.If document is
None
, only the document data will be uploaded. The new document entry will be named using slug, and will have default metadata.The stream returned by this function should be written to using the standard
Gio.OutputStream
methods, asynchronously or synchronously. Once the stream is closed (usingGio.OutputStream.close
()),GData.DocumentsService.finish_upload
() should be called on it to parse and return the updatedGData.DocumentsDocument
for the document. This must be done, as document isn’t updated in-place.In order to cancel the upload, a
Gio.Cancellable
passed in to cancellable must be cancelled usingGio.Cancellable.cancel
(). Cancelling the individualGio.OutputStream
operations on theGData.UploadStream
will not cancel the entire upload; merely the write or close operation in question. See theGData.UploadStream
:cancellable
for more details.Any upload errors will be thrown by the stream methods, and may come from the
GData.ServiceError
domain.New in version 0.8.0.
- upload_document_resumable(document, slug, content_type, content_length, query, cancellable)¶
- Parameters:
document (
GData.DocumentsDocument
orNone
) – theGData.DocumentsDocument
to insert, orNone
slug (
str
) – the filename to give to the uploaded documentcontent_type (
str
) – the content type of the uploaded datacontent_length (
int
) – the size (in bytes) of the file being uploadedquery (
GData.DocumentsUploadQuery
orNone
) – a query specifying parameters for the upload, orNone
cancellable (
Gio.Cancellable
orNone
) – aGio.Cancellable
for the entire upload stream, orNone
- Raises:
- Returns:
a
GData.UploadStream
to write the document data to, orNone
; unref withGObject.Object.unref
()- Return type:
Uploads a document to Google Documents, using the properties from document and the document data written to the resulting
GData.UploadStream
. If the document data does not need to be provided at the moment, just the metadata, useGData.Service.insert_entry
() instead (e.g. in the case of creating a new, empty file to be edited at a later date).Unlike
GData.DocumentsService.upload_document
(), this method performs aresumable upload which allows for correction of transmission errors without re-uploading the entire file. Use of this method is preferred over
GData.DocumentsService.upload_document
().If document is
None
, only the document data will be uploaded. The new document entry will be named using slug, and will have default metadata.If non-
None
, the query specifies parameters for the upload, such as aGData.DocumentsFolder
to upload the document into; and whether to treat the document as an opaque file, or convert it to a standard format. If query isNone
, the document will be uploaded into the root folder, and automatically converted to a standard format. No OCR or automatic language translation will be performed by default.If query is non-
None
andGData.DocumentsUploadQuery
:convert
isFalse
, document must be an instance ofGData.DocumentsDocument
. Otherwise, document must be a subclass of it, such asGData.DocumentsPresentation
.The stream returned by this function should be written to using the standard
Gio.OutputStream
methods, asynchronously or synchronously. Once the stream is closed (usingGio.OutputStream.close
()),GData.DocumentsService.finish_upload
() should be called on it to parse and return the updatedGData.DocumentsDocument
for the document. This must be done, as document isn’t updated in-place.In order to cancel the upload, a
Gio.Cancellable
passed in to cancellable must be cancelled usingGio.Cancellable.cancel
(). Cancelling the individualGio.OutputStream
operations on theGData.UploadStream
will not cancel the entire upload; merely the write or close operation in question. See theGData.UploadStream
:cancellable
for more details.Any upload errors will be thrown by the stream methods, and may come from the
GData.ServiceError
domain.New in version 0.13.0.