Skip to content

Commit

Permalink
💡 Update comments and strings with MultipartFile (#2308)
Browse files Browse the repository at this point in the history
Resolves #1889 (comment)

---------

Signed-off-by: Alex Li <github@alexv525.com>
Co-authored-by: Jonas Uekötter <ueman@users.noreply.github.com>
  • Loading branch information
AlexV525 and ueman authored Oct 7, 2024
1 parent 945d487 commit d0838a2
Show file tree
Hide file tree
Showing 3 changed files with 45 additions and 37 deletions.
1 change: 1 addition & 0 deletions dio/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
74 changes: 39 additions & 35 deletions dio/lib/src/multipart_file.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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<List<int>> Function() data,
this.length, {
Expand All @@ -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<int> value, {
String? filename,
Expand All @@ -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,
Expand All @@ -90,7 +90,6 @@ class MultipartFile {
utf8,
);
contentType = contentType.change(parameters: {'charset': encoding.name});

return MultipartFile.fromBytes(
encoding.encode(value),
filename: filename,
Expand Down Expand Up @@ -131,26 +130,28 @@ class MultipartFile {
String? filename,
DioMediaType? contentType,
final Map<String, List<String>>? 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<String, List<String>>? headers,
}) =>
multipartFileFromPathSync(
filePath,
filename: filename,
contentType: contentType,
headers: headers,
);
}) {
return multipartFileFromPathSync(
filePath,
filename: filename,
contentType: contentType,
headers: headers,
);
}

bool _isFinalized = false;

Expand All @@ -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.
Expand Down
7 changes: 5 additions & 2 deletions dio/test/multipart_file_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,11 @@ void main() async {
expect(e, isA<StateError>());
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.',
);
}

Expand Down

0 comments on commit d0838a2

Please sign in to comment.