apacheGH-49684: [MATLAB] Introduce deprecation warnings for "legacy" Feather V1 functions featherread and featherwrite (apache#49705)

kevingurney · sgilmore10 · web-flow · commit 4eca50770f7f · 2026-04-14T11:42:24.000-04:00
### Rationale for this change In response to apache#49231 and https://lists.apache.org/thread/1npvnhjb1xwz09zh8vnd079zt2q4o08l, this pull request introduces deprecation warnings for the public MATLAB `featherread` and `featherwrite` APIs that allow reading and writing "legacy" Feather V1 files. The solution of introducing deprecation warnings follows the pyarrow approach proposed in apache#49590. **Examples** `featherread` ```matlab >> featherread("out.feather") Warning: Reading from Feather V1 files is deprecated. Use arrow.io.ipc.RecordBatchFileReader to read from Feather V2 (Arrow IPC) files. > In featherread (line 30) ``` `featherwrite` ```matlab >> featherwrite("out.feather", array2table(1)) Warning: Writing to Feather V1 files is deprecated. Use arrow.io.ipc.RecordBatchFileWriter to write to Feather V2 (Arrow IPC) files. > In featherread (line 31) ``` ### What changes are included in this PR? 1. Introduced a new warning with identifier `arrow:io:feather:v1:FeatherWriteDeprecated` when calling `featherwrite.m`. 2. Introduced a new warning with identifier `arrow:io:feather:v1:FeatherReadDeprecated` when calling `featherread.m`. ### Are these changes tested? Yes. 1. Updated `matlab/test/tfeather.m` to suppress `featherread` and `featherwrite` deprecation warnings. 2. Added two new test cases to `tfeather.m`: `VerifyFeatherReadDeprecationWarning` and `VerifyFeatherWriteDeprecationWarning`. These test cases verify that the expected deprecation warnings are issued as expected. 3. Updated `matlab/test/arrow/io/feather/tRoundTrip.m` to suppress `featherread` deprecation warnings. ### Are there any user-facing changes? Yes. 1. The `featherread` and `featherwrite` functions are user-facing. With these changes, deprecation warnings will be displayed when invoking either of these functions. **Note**: these warnings can be turned off in MATLAB by calling ` warning("off", "arrow:io:feather:v1:FeatherWriteDeprecated")` and `warning("off", "arrow:io:feather:v1:FeatherReadDeprecated")`. ### Future Directions 1. We may want to consider moving `featherread` and `featherwrite` into a package like `arrow.io.feather.v1.*` to mirror the rest of the mlarrow APIs. Alternatively, we could consider removing these functions entirely. ### Notes 1. Thank you @ sgilmore10 for your help with this pull request! * GitHub Issue: apache#49684 Lead-authored-by: Kevin Gurney <kgurney@mathworks.com> Co-authored-by: Sarah Gilmore <sgilmore@mathworks.com> Signed-off-by: Kevin Gurney <kgurney@mathworks.com>
diff --git a/matlab/src/matlab/featherread.m b/matlab/src/matlab/featherread.m
@@ -27,6 +27,10 @@
         filename(1, 1) string {mustBeNonmissing, mustBeNonzeroLengthText}
     end
 
+    warning("arrow:io:feather:v1:FeatherReadDeprecated", ...
+        "Reading from Feather V1 files is deprecated. Use arrow.io.ipc.RecordBatchFileReader to read from Feather V2 (Arrow IPC) files.");
+
+
     typesToCast = [arrow.type.ID.UInt8, ...
                    arrow.type.ID.UInt16, ...
                    arrow.type.ID.UInt32, ...
diff --git a/matlab/src/matlab/featherwrite.m b/matlab/src/matlab/featherwrite.m
@@ -28,6 +28,9 @@ function featherwrite(filename, t)
         t table
     end
 
+    warning("arrow:io:feather:v1:FeatherWriteDeprecated", ...
+        "Writing to Feather V1 files is deprecated. Use arrow.io.ipc.RecordBatchFileWriter to write to Feather V2 (Arrow IPC) files.");
+
     recordBatch = arrow.recordBatch(t);
     writer = arrow.internal.io.feather.Writer(filename);
     writer.write(recordBatch);
diff --git a/matlab/test/arrow/io/feather/tRoundTrip.m b/matlab/test/arrow/io/feather/tRoundTrip.m
@@ -16,6 +16,15 @@
 % permissions and limitations under the License.
 classdef tRoundTrip < matlab.unittest.TestCase
 
+    methods(TestMethodSetup)
+
+        function suppressFeatherV1Warnings(testCase)
+            import matlab.unittest.fixtures.SuppressedWarningsFixture
+            testCase.applyFixture(SuppressedWarningsFixture("arrow:io:feather:v1:FeatherReadDeprecated"));
+        end
+
+    end
+
     methods(Test)
         function Basic(testCase)
             import matlab.unittest.fixtures.TemporaryFolderFixture
diff --git a/matlab/test/tfeather.m b/matlab/test/tfeather.m
@@ -22,6 +22,12 @@ function setupTempWorkingDirectory(testCase)
             import matlab.unittest.fixtures.WorkingFolderFixture;
             testCase.applyFixture(WorkingFolderFixture);
         end
+
+        function suppressFeatherV1Warnings(testCase)
+            import matlab.unittest.fixtures.SuppressedWarningsFixture
+            testCase.applyFixture(SuppressedWarningsFixture("arrow:io:feather:v1:FeatherReadDeprecated"));
+            testCase.applyFixture(SuppressedWarningsFixture("arrow:io:feather:v1:FeatherWriteDeprecated"));
+        end
         
     end
     
@@ -267,6 +273,29 @@ function UnicodeVariableNames(testCase)
             testCase.verifyEqual(actualTable, expectedTable);
         end
 
+        function VerifyFeatherReadDeprecationWarning(testCase)
+            filename = fullfile(pwd, 'temp.feather');
+
+            t = array2table([1, 2, 3]);
+            featherwrite(filename, t);
+            
+            warning("on", "arrow:io:feather:v1:FeatherReadDeprecated");
+            fcn = @() featherread(filename);
+            testCase.verifyWarning(fcn, "arrow:io:feather:v1:FeatherReadDeprecated")
+            warning("off", "arrow:io:feather:v1:FeatherReadDeprecated");
+        end
+
+        function VerifyFeatherWriteDeprecationWarning(testCase)
+            filename = fullfile(pwd, 'temp.feather');
+
+            t = array2table([1, 2, 3]);
+            
+            warning("on", "arrow:io:feather:v1:FeatherWriteDeprecated");
+            fcn = @() featherwrite(filename, t);
+            testCase.verifyWarning(fcn, "arrow:io:feather:v1:FeatherWriteDeprecated")
+            warning("off", "arrow:io:feather:v1:FeatherReadDeprecated");
+        end
+
     end
 end
 
