diff --git a/dio/CHANGELOG.md b/dio/CHANGELOG.md index 3ff5268d..4a43995d 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 8d451a4d..414bb050 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 b858736e..9684c991 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.', ); }