diff --git a/dropbox/base.py b/dropbox/base.py index 4d9e777..efe7b1b 100644 --- a/dropbox/base.py +++ b/dropbox/base.py @@ -4645,20 +4645,23 @@ def riviera_get_keyframes_async( self, file_id_or_url=None, scene_change_threshold=0.0, include_images=False ): """ - Asynchronous scene-change keyframe extraction for video files. Detects - scene changes in the source video and returns one representative - keyframe per detected scene, each tagged with its timestamp (seconds - from the start of the video) and scene-change score. Set `include_images - = true` to also receive each frame as a base64-encoded JPEG; when the - field is omitted the response carries keyframe metadata only. Supported - video formats: .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .flv, .m2t, .m2ts, - .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf, .oggtheora, .ogv, .rm, - .ts, .vob, .webm, .wmv. Unsupported formats return an - `unsupported_format_error`. Limits: the source file must be at most 10 - GB. To keep responses within service limits the number of keyframes and - the total image payload are bounded; requests that would exceed these - limits return a `limit_exceeded_error` -- raise `scene_change_threshold` - or set `include_images = false` to stay within bounds. + Deprecated: use :meth:`riviera_extract_async` with `extract_type` set to + ``ExtractType.keyframes`` instead, which takes the same options. This + route will be turned off by December 31, 2026. Asynchronous scene-change + keyframe extraction for video files. Detects scene changes in the source + video and returns one representative keyframe per detected scene, each + tagged with its timestamp (seconds from the start of the video) and + scene-change score. Set `include_images = true` to also receive each + frame as a base64-encoded JPEG; when the field is omitted the response + carries keyframe metadata only. Supported video formats: .3gp, .3gpp, + .3gpp2, .asf, .avi, .dv, .flv, .m2t, .m2ts, .m4v, .mkv, .mov, .mp4, + .mpeg, .mpg, .mts, .mxf, .oggtheora, .ogv, .rm, .ts, .vob, .webm, .wmv. + Unsupported formats return an `unsupported_format_error`. Limits: the + source file must be at most 10 GB. To keep responses within service + limits the number of keyframes and the total image payload are bounded; + requests that would exceed these limits return a `limit_exceeded_error` + -- raise `scene_change_threshold` or set `include_images = false` to + stay within bounds. Route attributes: scope: files.content.read @@ -4685,6 +4688,10 @@ def riviera_get_keyframes_async( :type include_images: bool :rtype: :class:`dropbox.async_.LaunchResultBase` """ + warnings.warn( + "get_keyframes_async is deprecated.", + DeprecationWarning, + ) arg = riviera.GetKeyframesArgs(file_id_or_url, scene_change_threshold, include_images) r = self.request( riviera.get_keyframes_async, @@ -4710,6 +4717,10 @@ def riviera_get_keyframes_async_check(self, async_job_id): If this raises, ApiError will contain: :class:`dropbox.async_.PollError` """ + warnings.warn( + "get_keyframes_async/check is deprecated.", + DeprecationWarning, + ) arg = async_.PollArg(async_job_id) r = self.request( riviera.get_keyframes_async_check, @@ -4721,9 +4732,12 @@ def riviera_get_keyframes_async_check(self, async_job_id): def riviera_get_markdown_async(self, file_id_or_url=None, enable_ocr=False, embed_images=False): """ - Asynchronous document-to-markdown conversion for supported file formats. - Supported formats: .binder, .docx, .html, .paper, .papert, .pptx, .xlsx, - .gsheet, .ods, .pdf. Files in other formats fail with + Deprecated: use :meth:`riviera_extract_async` with `extract_type` set to + ``ExtractType.markdown`` instead, which takes the same options. This + route will be turned off by December 31, 2026. Asynchronous + document-to-markdown conversion for supported file formats. Supported + formats: .binder, .docx, .html, .paper, .papert, .pptx, .xlsx, .gsheet, + .ods, .pdf. Files in other formats fail with ``MarkdownConversionApiV2Error.user_error``. Size limit: the source file must be at most 50 MB. Larger files fail with ``MarkdownConversionApiV2Error.user_error``. The markdown is not @@ -4750,6 +4764,10 @@ def riviera_get_markdown_async(self, file_id_or_url=None, enable_ocr=False, embe :type embed_images: bool :rtype: :class:`dropbox.async_.LaunchResultBase` """ + warnings.warn( + "get_markdown_async is deprecated.", + DeprecationWarning, + ) arg = riviera.GetMarkdownArgs(file_id_or_url, enable_ocr, embed_images) r = self.request( riviera.get_markdown_async, @@ -4775,6 +4793,10 @@ def riviera_get_markdown_async_check(self, async_job_id): If this raises, ApiError will contain: :class:`dropbox.async_.PollError` """ + warnings.warn( + "get_markdown_async/check is deprecated.", + DeprecationWarning, + ) arg = async_.PollArg(async_job_id) r = self.request( riviera.get_markdown_async_check, @@ -4858,16 +4880,19 @@ def riviera_get_metadata_async_check(self, async_job_id): def riviera_get_ocr_async(self, file_id_or_url=None): """ - Asynchronous OCR (optical character recognition) text extraction for - images and PDFs, including scanned / non-text PDFs. Supported formats: - - Image formats: .bmp, .gif, .heic, .jpeg, .jpg, .png, .tif, .tiff, .webp. - - PDF format: .pdf. Unsupported formats return an - `unsupported_format_error`. For the `url` variant only Dropbox shared - links are supported; external URLs return `unsupported_format_error`. - Text-based PDFs already carry a text layer, so OCR is not run against - them and the result is empty; use `get_text_async` to read the embedded - text layer of such a PDF. The result carries the extracted words as - plain text, plus the same content as hOCR with per-word coordinates. + Deprecated: use :meth:`riviera_extract_async` with `extract_type` set to + ``ExtractType.ocr`` instead, which takes the same options. This route + will be turned off by December 31, 2026. Asynchronous OCR (optical + character recognition) text extraction for images and PDFs, including + scanned / non-text PDFs. Supported formats: - Image formats: .bmp, .gif, + .heic, .jpeg, .jpg, .png, .tif, .tiff, .webp. - PDF format: .pdf. + Unsupported formats return an `unsupported_format_error`. For the `url` + variant only Dropbox shared links are supported; external URLs return + `unsupported_format_error`. Text-based PDFs already carry a text layer, + so OCR is not run against them and the result is empty; use + `get_text_async` to read the embedded text layer of such a PDF. The + result carries the extracted words as plain text, plus the same content + as hOCR with per-word coordinates. Route attributes: scope: files.content.read @@ -4884,6 +4909,10 @@ def riviera_get_ocr_async(self, file_id_or_url=None): :type file_id_or_url: Nullable[:class:`dropbox.riviera.FileIdOrUrl`] :rtype: :class:`dropbox.async_.LaunchResultBase` """ + warnings.warn( + "get_ocr_async is deprecated.", + DeprecationWarning, + ) arg = riviera.GetOcrArgs(file_id_or_url) r = self.request( riviera.get_ocr_async, @@ -4909,6 +4938,10 @@ def riviera_get_ocr_async_check(self, async_job_id): If this raises, ApiError will contain: :class:`dropbox.async_.PollError` """ + warnings.warn( + "get_ocr_async/check is deprecated.", + DeprecationWarning, + ) arg = async_.PollArg(async_job_id) r = self.request( riviera.get_ocr_async_check, @@ -4920,14 +4953,16 @@ def riviera_get_ocr_async_check(self, async_job_id): def riviera_get_text_async(self, file_id_or_url=None): """ - Asynchronous plain-text extraction from documents. Supported formats - include: - Word processing: .doc, .docx, .docm, .rtf. - Presentations: - .ppt, .pptx, .pptm. - Spreadsheets: .xls, .xlsx, .xlsm. - PDF: .pdf. - - Dropbox document types: .paper, .papert, .binder, .gdoc, .gsheet, - .gslides. - Plain text / subtitles: .txt, .vtt. Unsupported formats - return an `unsupported_format_error`. For the `url` variant only Dropbox - shared links are supported; external URLs return - `unsupported_format_error`. + Deprecated: use :meth:`riviera_extract_async` with `extract_type` set to + ``ExtractType.text`` instead, which takes the same options. This route + will be turned off by December 31, 2026. Asynchronous plain-text + extraction from documents. Supported formats include: - Word processing: + .doc, .docx, .docm, .rtf. - Presentations: .ppt, .pptx, .pptm. - + Spreadsheets: .xls, .xlsx, .xlsm. - PDF: .pdf. - Dropbox document types: + .paper, .papert, .binder, .gdoc, .gsheet, .gslides. - Plain text / + subtitles: .txt, .vtt. Unsupported formats return an + `unsupported_format_error`. For the `url` variant only Dropbox shared + links are supported; external URLs return `unsupported_format_error`. Route attributes: scope: files.content.read @@ -4945,6 +4980,10 @@ def riviera_get_text_async(self, file_id_or_url=None): :type file_id_or_url: Nullable[:class:`dropbox.riviera.FileIdOrUrl`] :rtype: :class:`dropbox.async_.LaunchResultBase` """ + warnings.warn( + "get_text_async is deprecated.", + DeprecationWarning, + ) arg = riviera.GetTextArgs(file_id_or_url) r = self.request( riviera.get_text_async, @@ -4970,6 +5009,10 @@ def riviera_get_text_async_check(self, async_job_id): If this raises, ApiError will contain: :class:`dropbox.async_.PollError` """ + warnings.warn( + "get_text_async/check is deprecated.", + DeprecationWarning, + ) arg = async_.PollArg(async_job_id) r = self.request( riviera.get_text_async_check, @@ -4987,15 +5030,18 @@ def riviera_get_transcript_async( audio_language="", ): """ - Asynchronous transcript generation for audio and video files. Supported - audio formats: .aac, .aif, .aiff, .flac, .m4a, .m4r, .mp3, .oga, .ogg, - .wav, .wma. Supported video formats: .3gp, .3gpp, .3gpp2, .asf, .avi, - .dv, .flv, .m2t, .m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf, - .oggtheora, .ogv, .rm, .ts, .vob, .webm, .wmv. Files in other formats - fail with ``ContentApiV2Error.user_error``. Size limits: the source file - must be at most 10 GB and its audio track at most 1 hour in duration. - Files exceeding either limit fail with ``ContentApiV2Error.user_error``. - The transcript is not returned by this route. Poll + Deprecated: use :meth:`riviera_extract_async` with `extract_type` set to + ``ExtractType.transcript`` instead, which takes the same options. This + route will be turned off by December 31, 2026. Asynchronous transcript + generation for audio and video files. Supported audio formats: .aac, + .aif, .aiff, .flac, .m4a, .m4r, .mp3, .oga, .ogg, .wav, .wma. Supported + video formats: .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .flv, .m2t, .m2ts, + .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf, .oggtheora, .ogv, .rm, + .ts, .vob, .webm, .wmv. Files in other formats fail with + ``ContentApiV2Error.user_error``. Size limits: the source file must be + at most 10 GB and its audio track at most 1 hour in duration. Files + exceeding either limit fail with ``ContentApiV2Error.user_error``. The + transcript is not returned by this route. Poll :meth:`riviera_get_transcript_async_check` with the returned async job ID until it reports ``GetTranscriptAsyncCheckResult.complete`` or ``GetTranscriptAsyncCheckResult.failed``. @@ -5027,6 +5073,10 @@ def riviera_get_transcript_async( :type audio_language: str :rtype: :class:`dropbox.async_.LaunchResultBase` """ + warnings.warn( + "get_transcript_async is deprecated.", + DeprecationWarning, + ) arg = riviera.GetTranscriptArgs( file_id_or_url, timestamp_level, included_special_words, audio_language ) @@ -5054,6 +5104,10 @@ def riviera_get_transcript_async_check(self, async_job_id): If this raises, ApiError will contain: :class:`dropbox.async_.PollError` """ + warnings.warn( + "get_transcript_async/check is deprecated.", + DeprecationWarning, + ) arg = async_.PollArg(async_job_id) r = self.request( riviera.get_transcript_async_check, diff --git a/dropbox/riviera.py b/dropbox/riviera.py index fd43cd3..f4b1aea 100644 --- a/dropbox/riviera.py +++ b/dropbox/riviera.py @@ -7212,7 +7212,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_keyframes_async = bb.Route( "get_keyframes_async", 1, - False, + True, GetKeyframesArgs_validator, async_.LaunchResultBase_validator, bv.Void(), @@ -7221,7 +7221,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_keyframes_async_check = bb.Route( "get_keyframes_async/check", 1, - False, + True, async_.PollArg_validator, GetKeyframesAsyncCheckResult_validator, async_.PollError_validator, @@ -7230,7 +7230,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_markdown_async = bb.Route( "get_markdown_async", 1, - False, + True, GetMarkdownArgs_validator, async_.LaunchResultBase_validator, bv.Void(), @@ -7239,7 +7239,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_markdown_async_check = bb.Route( "get_markdown_async/check", 1, - False, + True, async_.PollArg_validator, GetMarkdownAsyncCheckResult_validator, async_.PollError_validator, @@ -7266,7 +7266,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_ocr_async = bb.Route( "get_ocr_async", 1, - False, + True, GetOcrArgs_validator, async_.LaunchResultBase_validator, bv.Void(), @@ -7275,7 +7275,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_ocr_async_check = bb.Route( "get_ocr_async/check", 1, - False, + True, async_.PollArg_validator, GetOcrAsyncCheckResult_validator, async_.PollError_validator, @@ -7284,7 +7284,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_text_async = bb.Route( "get_text_async", 1, - False, + True, GetTextArgs_validator, async_.LaunchResultBase_validator, bv.Void(), @@ -7293,7 +7293,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_text_async_check = bb.Route( "get_text_async/check", 1, - False, + True, async_.PollArg_validator, GetTextAsyncCheckResult_validator, async_.PollError_validator, @@ -7302,7 +7302,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_transcript_async = bb.Route( "get_transcript_async", 1, - False, + True, GetTranscriptArgs_validator, async_.LaunchResultBase_validator, bv.Void(), @@ -7311,7 +7311,7 @@ def _process_custom_annotations(self, annotation_type, field_path, processor): get_transcript_async_check = bb.Route( "get_transcript_async/check", 1, - False, + True, async_.PollArg_validator, GetTranscriptAsyncCheckResult_validator, async_.PollError_validator, diff --git a/spec b/spec index 4f037ce..1a7e203 160000 --- a/spec +++ b/spec @@ -1 +1 @@ -Subproject commit 4f037ce011ede1c5bb21a10d0ac7c3a83c7d2458 +Subproject commit 1a7e203670ccafba84d15a560aca238cfd8dab03