From 63f858ffaad96fdf2a07c40d56e95a95b641fe4c Mon Sep 17 00:00:00 2001 From: PRANTA Dutta Date: Wed, 27 May 2026 11:41:52 +0600 Subject: [PATCH 1/2] [path_provider] Document null vs UnsupportedError return semantics The dartdoc on getDownloadsDirectory previously only mentioned the UnsupportedError case, but the function also returns null when a platform supports the concept of a downloads directory but no such directory is currently available (for example, Linux without xdg-user-dir installed, or when xdg-user-dir fails when called). Document both return-value semantics on the public API method in path_provider, and mirror the implementation contract on PathProviderPlatform.getDownloadsPath in path_provider_platform_interface. Wording follows the explanations @stuartmorgan-g and @Hixie gave in the issue thread (flutter/flutter#143238). Fixes flutter/flutter#143238 --- packages/path_provider/path_provider/CHANGELOG.md | 2 ++ .../path_provider/path_provider/lib/path_provider.dart | 9 +++++++-- .../path_provider_platform_interface/CHANGELOG.md | 2 ++ .../lib/path_provider_platform_interface.dart | 8 ++++++++ 4 files changed, 19 insertions(+), 2 deletions(-) diff --git a/packages/path_provider/path_provider/CHANGELOG.md b/packages/path_provider/path_provider/CHANGELOG.md index 47f9da7e2deb..f5394fdd2209 100644 --- a/packages/path_provider/path_provider/CHANGELOG.md +++ b/packages/path_provider/path_provider/CHANGELOG.md @@ -3,6 +3,8 @@ * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. * Updates README to reflect currently supported OS versions for the latest versions of the endorsed platform implementations. +* Documents the difference between a `null` return and an `UnsupportedError` + from `getDownloadsDirectory`. * Applications built with older versions of Flutter will continue to use compatible versions of the platform implementations. diff --git a/packages/path_provider/path_provider/lib/path_provider.dart b/packages/path_provider/path_provider/lib/path_provider.dart index d855c260889e..1e1d299cf55c 100644 --- a/packages/path_provider/path_provider/lib/path_provider.dart +++ b/packages/path_provider/path_provider/lib/path_provider.dart @@ -217,8 +217,13 @@ Future?> getExternalStorageDirectories({ /// The returned directory is not guaranteed to exist, so clients should verify /// that it does before using it, and potentially create it if necessary. /// -/// Throws an [UnsupportedError] if this is not supported on the current -/// platform. +/// Returns `null` when the current platform supports the concept of a +/// downloads directory but no such directory is currently available. For +/// example, on Linux this can happen when `xdg-user-dir` is not installed +/// or fails when called. +/// +/// Throws an [UnsupportedError] when the current platform has no concept of +/// a downloads directory at all. Future getDownloadsDirectory() async { final String? path = await _platform.getDownloadsPath(); if (path == null) { diff --git a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md index f7c254e96335..70f14eb34815 100644 --- a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md +++ b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md @@ -1,6 +1,8 @@ ## NEXT * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. +* Documents the implementation contract for `null` versus `UnsupportedError` + return semantics on `getDownloadsPath`. ## 2.1.2 diff --git a/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart b/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart index 22a1676cc84b..8ee796bf1b36 100644 --- a/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart +++ b/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart @@ -105,6 +105,14 @@ abstract class PathProviderPlatform extends PlatformInterface { /// Path to the directory where downloaded files can be stored. /// This is typically only relevant on desktop operating systems. + /// + /// Implementations should return `null` when the platform supports the + /// concept of a downloads directory but no such directory is currently + /// available (for example, on Linux when `xdg-user-dir` is not installed + /// or fails when called). + /// + /// Implementations should throw an [UnsupportedError] when the platform + /// has no concept of a downloads directory at all. Future getDownloadsPath() { throw UnimplementedError('getDownloadsPath() has not been implemented.'); } From 84919530c56fe8c884f6cc775aa5094044e161e5 Mon Sep 17 00:00:00 2001 From: PRANTA Dutta Date: Wed, 27 May 2026 23:19:43 +0600 Subject: [PATCH 2/2] Address review: fix CHANGELOG nesting, bump versions - Fix CHANGELOG.md nesting so the existing 'Applications built with older versions...' sub-bullet stays correctly nested under the README bullet (gemini-code-assist bot finding). - Bump path_provider 2.1.5 -> 2.1.6 and path_provider_platform_interface 2.1.2 -> 2.1.3, replacing the NEXT heading with the new version per the flutter/packages CHANGELOG conventions for continuous releases. --- packages/path_provider/path_provider/CHANGELOG.md | 6 +++--- packages/path_provider/path_provider/pubspec.yaml | 2 +- .../path_provider_platform_interface/CHANGELOG.md | 2 +- .../path_provider_platform_interface/pubspec.yaml | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/path_provider/path_provider/CHANGELOG.md b/packages/path_provider/path_provider/CHANGELOG.md index f5394fdd2209..e1fc0658d030 100644 --- a/packages/path_provider/path_provider/CHANGELOG.md +++ b/packages/path_provider/path_provider/CHANGELOG.md @@ -1,12 +1,12 @@ -## NEXT +## 2.1.6 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. * Updates README to reflect currently supported OS versions for the latest versions of the endorsed platform implementations. -* Documents the difference between a `null` return and an `UnsupportedError` - from `getDownloadsDirectory`. * Applications built with older versions of Flutter will continue to use compatible versions of the platform implementations. +* Documents the difference between a `null` return and an `UnsupportedError` + from `getDownloadsDirectory`. ## 2.1.5 diff --git a/packages/path_provider/path_provider/pubspec.yaml b/packages/path_provider/path_provider/pubspec.yaml index bb3acf4907cb..92b660ef2cae 100644 --- a/packages/path_provider/path_provider/pubspec.yaml +++ b/packages/path_provider/path_provider/pubspec.yaml @@ -2,7 +2,7 @@ name: path_provider description: Flutter plugin for getting commonly used locations on host platform file systems, such as the temp and app data directories. repository: https://github.com/flutter/packages/tree/main/packages/path_provider/path_provider issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22 -version: 2.1.5 +version: 2.1.6 environment: sdk: ^3.10.0 diff --git a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md index 70f14eb34815..08cc4c826617 100644 --- a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md +++ b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md @@ -1,4 +1,4 @@ -## NEXT +## 2.1.3 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. * Documents the implementation contract for `null` versus `UnsupportedError` diff --git a/packages/path_provider/path_provider_platform_interface/pubspec.yaml b/packages/path_provider/path_provider_platform_interface/pubspec.yaml index 37dd1c72b895..d65d8fe1e898 100644 --- a/packages/path_provider/path_provider_platform_interface/pubspec.yaml +++ b/packages/path_provider/path_provider_platform_interface/pubspec.yaml @@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/path_provider issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22 # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 2.1.2 +version: 2.1.3 environment: sdk: ^3.10.0