docs: deprecate get_corporate_announcements (#616)

Author: hiohiohio

alpaca/trading/client.py

@@ -1,47 +1,47 @@
+import json
+import warnings
+from typing import List, Optional, Union
 from uuid import UUID
+
 from pydantic import TypeAdapter
-import json
 
 from alpaca.common import RawData
+from alpaca.common.enums import BaseURL
+from alpaca.common.rest import RESTClient
 from alpaca.common.utils import (
+    validate_symbol_or_asset_id,
     validate_symbol_or_contract_id,
     validate_uuid_id_param,
-    validate_symbol_or_asset_id,
 )
-from alpaca.common.rest import RESTClient
-from typing import Optional, List, Union
-from alpaca.common.enums import BaseURL
-
+from alpaca.trading.models import (
+    AccountConfiguration,
+    Asset,
+    Calendar,
+    Clock,
+    ClosePositionResponse,
+    CorporateActionAnnouncement,
+    OptionContract,
+    OptionContractsResponse,
+    Order,
+    PortfolioHistory,
+    Position,
+    TradeAccount,
+    Watchlist,
+)
 from alpaca.trading.requests import (
-    GetCalendarRequest,
+    CancelOrderResponse,
     ClosePositionRequest,
+    CreateWatchlistRequest,
     GetAssetsRequest,
+    GetCalendarRequest,
+    GetCorporateAnnouncementsRequest,
     GetOptionContractsRequest,
+    GetOrderByIdRequest,
+    GetOrdersRequest,
     GetPortfolioHistoryRequest,
     OrderRequest,
-    GetOrdersRequest,
     ReplaceOrderRequest,
-    GetOrderByIdRequest,
-    CancelOrderResponse,
-    CreateWatchlistRequest,
     UpdateWatchlistRequest,
-    GetCorporateAnnouncementsRequest,
-)
-
-from alpaca.trading.models import (
-    OptionContract,
-    OptionContractsResponse,
-    Order,
-    PortfolioHistory,
-    Position,
-    ClosePositionResponse,
-    Asset,
-    Watchlist,
-    Clock,
-    Calendar,
-    TradeAccount,
-    CorporateActionAnnouncement,
-    AccountConfiguration,
 )
 
 
@@ -678,12 +678,23 @@ def get_corporate_announcements(
         self, filter: GetCorporateAnnouncementsRequest
     ) -> Union[List[CorporateActionAnnouncement], RawData]:
         """
+        DEPRECATED: Please use the new corporate actions endpoint instead.
+        alpaca.data.historical.corporate_actions.CorporateActionsClient.get_corporate_actions()
+        ref. https://docs.alpaca.markets/reference/corporateactions-1
+
         Returns corporate action announcements data given specified search criteria.
+
         Args:
             filter (GetCorporateAnnouncementsRequest): The parameters to filter the search by.
         Returns:
             List[CorporateActionAnnouncement]: The resulting announcements from the search.
         """
+        warnings.warn(
+            "get_corporate_announcements is deprecated and will be removed in a future version."
+            "Please use alpaca.data.historical.corporate_actions.CorporateActionsClient.get_corporate_actions() instead",
+            DeprecationWarning,
+        )
+
         params = filter.to_request_fields() if filter else {}
 
         if "ca_types" in params and isinstance(params["ca_types"], list):

tests/trading/trading_client/test_corporate_announcements.py

@@ -1,12 +1,12 @@
 from typing import List
 
+import pytest
+
 from alpaca.common.enums import BaseURL
+from alpaca.trading.client import TradingClient
 from alpaca.trading.enums import CorporateActionType
-from alpaca.trading.models import (
-    CorporateActionAnnouncement,
-)
+from alpaca.trading.models import CorporateActionAnnouncement
 from alpaca.trading.requests import GetCorporateAnnouncementsRequest
-from alpaca.trading.client import TradingClient
 
 
 def test_get_announcements(reqmock, trading_client: TradingClient):
@@ -71,7 +71,8 @@ def test_get_announcements(reqmock, trading_client: TradingClient):
         ca_types=[ca_types], since=since, until=until
     )
 
-    response = trading_client.get_corporate_announcements(ca_filter)
+    with pytest.deprecated_call():
+        response = trading_client.get_corporate_announcements(ca_filter)
 
     assert reqmock.called_once
     assert isinstance(response, List)