From d0838a25cefeafd253fb2fea6cd84c62d5edc5e6 Mon Sep 17 00:00:00 2001 From: Alex Li Date: Mon, 7 Oct 2024 17:57:24 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20Update=20comments=20and=20string?= =?UTF-8?q?s=20with=20`MultipartFile`=20(#2308)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves https://github.com/cfug/dio/pull/1889#issuecomment-2364208740 --------- Signed-off-by: Alex Li Co-authored-by: Jonas Uekötter --- dio/CHANGELOG.md | 1 + dio/lib/src/multipart_file.dart | 74 ++++++++++++++++--------------- dio/test/multipart_file_test.dart | 7 ++- 3 files changed, 45 insertions(+), 37 deletions(-) diff --git a/dio/CHANGELOG.md b/dio/CHANGELOG.md index 3ff5268d3..4a43995d3 100644 --- a/dio/CHANGELOG.md +++ b/dio/CHANGELOG.md @@ -5,6 +5,7 @@ See the [Migration Guide][] for the complete breaking changes list.** ## Unreleased +- Update comments and strings with `MultipartFile`. - Removes redundant warnings when composing request options on Web. ## 5.7.0 diff --git a/dio/lib/src/multipart_file.dart b/dio/lib/src/multipart_file.dart index 8d451a4d3..414bb050d 100644 --- a/dio/lib/src/multipart_file.dart +++ b/dio/lib/src/multipart_file.dart @@ -11,20 +11,18 @@ import 'utils.dart'; /// The type (alias) for specifying the content-type of the `MultipartFile`. typedef DioMediaType = MediaType; -/// A file to be uploaded as part of a [MultipartRequest]. This doesn't need to -/// correspond to a physical file. -/// -/// MultipartFile is based on stream, and a stream can be read only once, -/// so the same MultipartFile can't be read multiple times. +/// An upload content that is a part of `MultipartRequest`. +/// This doesn't need to correspond to a physical file. class MultipartFile { /// Creates a new [MultipartFile] from a chunked [Stream] of bytes. The length /// of the file in bytes must be known in advance. If it's not, read the data /// from the stream and use [MultipartFile.fromBytes] instead. /// - /// [contentType] currently defaults to `application/octet-stream`, but in the - /// future may be inferred from [filename]. + /// [contentType] currently defaults to `application/octet-stream`, + /// but it may be inferred from [filename] in the future. @Deprecated( - 'MultipartFile.clone() will not work when the stream is provided, use the MultipartFile.fromStream instead.' + 'MultipartFile() is not cloneable when the stream is consumed, ' + 'use MultipartFile.fromStream() instead.' 'This will be removed in 6.0.0', ) MultipartFile( @@ -37,12 +35,13 @@ class MultipartFile { headers = caseInsensitiveKeyMap(headers), contentType = contentType ?? MediaType('application', 'octet-stream'); - /// Creates a new [MultipartFile] from a chunked [Stream] of bytes. The length - /// of the file in bytes must be known in advance. If it's not, read the data - /// from the stream and use [MultipartFile.fromBytes] instead. + /// Creates a new [MultipartFile] from a creation method that creates + /// chunked [Stream] of bytes. The length of the file in bytes must be known + /// in advance. If it's not, read the data from the stream and use + /// [MultipartFile.fromBytes] instead. /// - /// [contentType] currently defaults to `application/octet-stream`, but in the - /// future may be inferred from [filename]. + /// [contentType] currently defaults to `application/octet-stream`, + /// but it may be inferred from [filename] in the future. MultipartFile.fromStream( Stream> Function() data, this.length, { @@ -55,8 +54,8 @@ class MultipartFile { /// Creates a new [MultipartFile] from a byte array. /// - /// [contentType] currently defaults to `application/octet-stream`, but in the - /// future may be inferred from [filename]. + /// [contentType] currently defaults to `application/octet-stream`, + /// but it may be inferred from [filename] in the future. factory MultipartFile.fromBytes( List value, { String? filename, @@ -76,8 +75,9 @@ class MultipartFile { /// /// The encoding to use when translating [value] into bytes is taken from /// [contentType] if it has a charset set. Otherwise, it defaults to UTF-8. - /// [contentType] currently defaults to `text/plain; charset=utf-8`, but in - /// the future may be inferred from [filename]. + /// + /// [contentType] currently defaults to `text/plain; charset=utf-8`, + /// but it may be inferred from [filename] in the future. factory MultipartFile.fromString( String value, { String? filename, @@ -90,7 +90,6 @@ class MultipartFile { utf8, ); contentType = contentType.change(parameters: {'charset': encoding.name}); - return MultipartFile.fromBytes( encoding.encode(value), filename: filename, @@ -131,26 +130,28 @@ class MultipartFile { String? filename, DioMediaType? contentType, final Map>? headers, - }) => - multipartFileFromPath( - filePath, - filename: filename, - contentType: contentType, - headers: headers, - ); + }) { + return multipartFileFromPath( + filePath, + filename: filename, + contentType: contentType, + headers: headers, + ); + } static MultipartFile fromFileSync( String filePath, { String? filename, DioMediaType? contentType, final Map>? headers, - }) => - multipartFileFromPathSync( - filePath, - filename: filename, - contentType: contentType, - headers: headers, - ); + }) { + return multipartFileFromPathSync( + filePath, + filename: filename, + contentType: contentType, + headers: headers, + ); + } bool _isFinalized = false; @@ -159,12 +160,15 @@ class MultipartFile { throw StateError( 'The MultipartFile has already been finalized. ' 'This typically means you are using ' - 'the same MultipartFile in repeated requests.', + 'the same MultipartFile in repeated requests.\n' + 'Use MultipartFile.clone() or create a new MultipartFile ' + 'for further usages.', ); } _isFinalized = true; - return _dataBuilder() - .map((e) => e is Uint8List ? e : Uint8List.fromList(e)); + return _dataBuilder().map( + (e) => e is Uint8List ? e : Uint8List.fromList(e), + ); } /// Clone MultipartFile, returning a new instance of the same object. diff --git a/dio/test/multipart_file_test.dart b/dio/test/multipart_file_test.dart index b858736ee..9684c9910 100644 --- a/dio/test/multipart_file_test.dart +++ b/dio/test/multipart_file_test.dart @@ -63,8 +63,11 @@ void main() async { expect(e, isA()); expect( (e as StateError).message, - 'The MultipartFile has already been finalized. This typically ' - 'means you are using the same MultipartFile in repeated requests.', + 'The MultipartFile has already been finalized. ' + 'This typically means you are using the same MultipartFile ' + 'in repeated requests.\n' + 'Use MultipartFile.clone() or create a new MultipartFile ' + 'for further usages.', ); }