feat: Add auction data handling to stock historical data client #576

River-Shi · 2025-04-08T14:06:33Z

Introduced StockAuctionsRequest for auction data requests.
Implemented get_stock_auction method in StockHistoricalDataClient to retrieve auction data.
Added Auction and AuctionSet models for structured auction data representation.
Updated mappings to include auction-related fields.
Created example usage for fetching auction data in examples/stocks/test.py.

- Introduced `StockAuctionsRequest` for auction data requests. - Implemented `get_stock_auction` method in `StockHistoricalDataClient` to retrieve auction data. - Added `Auction` and `AuctionSet` models for structured auction data representation. - Updated mappings to include auction-related fields. - Created example usage for fetching auction data in `examples/stocks/test.py`.

- Deleted `examples/stocks/test.py` which contained example usage for fetching auction data using the `StockHistoricalDataClient`. - This cleanup is part of the ongoing effort to streamline example files and focus on essential components.

…tting - Added missing commas in the function signatures of `validate_symbol_or_asset_id` and `validate_symbol_or_contract_id` for consistency. - Improved code formatting in `BaseTimeseriesDataRequest`, `StockHistoricalDataClient`, and `Auction` classes by removing unnecessary blank lines and ensuring proper spacing. - Enhanced readability and maintainability of the codebase.

River-Shi · 2025-04-09T12:47:51Z

I ve reformatted the file using black.

hiohiohio

Thank you for this PR! Overall LGTM! Left some comments. Could you please consider them?

hiohiohio · 2025-04-12T10:22:54Z

alpaca/data/historical/stock.py

@@ -72,6 +73,25 @@ def __init__(
            raw_data=raw_data,
        )

+    def get_stock_auction(self, request_params: StockAuctionsRequest):


Could we use plural?

Suggested change

def get_stock_auction(self, request_params: StockAuctionsRequest):

def get_stock_auctions(self, request_params: StockAuctionsRequest):

hiohiohio · 2025-04-12T10:28:37Z

alpaca/data/requests.py

+# ############################## Auctions ################################# #
+
+
+class StockAuctionsRequest(BaseTimeseriesDataRequest):


Could you please write docstring and also add to api_reference?

alpaca-py/docs/api_reference/data/stock/requests.rst

Line 4 in e16df12

hiohiohio · 2025-04-12T11:01:38Z

alpaca/data/models/auctions.py

+                for auction in auctions:
+                    c = auction.get("c")
+                    o = auction.get("o")
+
+                    if c is not None:
+                        auction_data.extend(c)
+                    if o is not None:
+                        auction_data.extend(o)


discussion: I felt it might be good to have indicator or separation between open and close. even though it might be possible to know based on timestamp. prefer to put something easy to distinguish.
idea: how about adding another attribuite i.e. open or close?

hiohiohio · 2025-04-12T11:02:31Z

alpaca/data/models/auctions.py

+    """Represents one auction of aggregated trade data over a specified interval.
+
+    Attributes:
+        symbol (str): The ticker identifier for the security whose data forms the bar.


could you please add other attribuites to docstring?

- Added `auction_type` field to the `Auction` model for better auction data representation. - Updated `StockAuctionsRequest` with detailed docstring for clarity on parameters. - Renamed `get_stock_auction` method to `get_stock_auctions` for consistency with plural naming conventions. - Updated mappings to include the new `auction_type` field. - Enhanced API documentation for auction-related models and requests.

hiohiohio

Overall LGTM! sorry, left one more comment. could you please address the comment?

hiohiohio · 2025-04-14T00:50:15Z

alpaca/data/models/auctions.py

+                    if o is not None:
+                        for open_auction in o:
+                            if open_auction:
+                                open_auction["at"] = "OPEN"
+                        auction_data.extend(o)


How about putting open first before close as timestamp could be orderd by asc.

I think we can use orderby timestamp in the final dataframe, and then open will be before close.

Yeah. You are right. For the dataframe, it is easy. But also we have AuctionSet object and if we change here, the process not required in dataframe level as well? Do you have any concern to change order here?

Are you saying that the order of the AuctionSet should be consistent with the order of the dataframe?

What I thought is order by open => close would be nicer than close => open order in a day.
currently:

{ "data": { "SPY": [ { "auction_type": "CLOSE", ... "timestamp": datetime.datetime( 2025, 4, 2, 20, 0, 0, 42680, tzinfo=TzInfo(UTC) ), }, ... { "auction_type": "OPEN", ... "timestamp": datetime.datetime( 2025, 4, 2, 13, 30, 0, 330621, tzinfo=TzInfo(UTC) ), }, ... { "auction_type": "CLOSE", ... "timestamp": datetime.datetime( 2025, 4, 3, 20, 0, 0, 130854, tzinfo=TzInfo(UTC) ), }, ... { "auction_type": "OPEN", ... "timestamp": datetime.datetime( 2025, 4, 3, 13, 30, 0, 692296, tzinfo=TzInfo(UTC) ), }, ... ] } }

What I thought good is:

{ "data": { "SPY": [ { "auction_type": "OPEN", ... "timestamp": datetime.datetime( 2025, 4, 2, 13, 30, 0, 330621, tzinfo=TzInfo(UTC) ), }, ... { "auction_type": "CLOSE", ... "timestamp": datetime.datetime( 2025, 4, 2, 20, 0, 0, 42680, tzinfo=TzInfo(UTC) ), }, ... { "auction_type": "OPEN", ... "timestamp": datetime.datetime( 2025, 4, 3, 13, 30, 0, 692296, tzinfo=TzInfo(UTC) ), }, ... { "auction_type": "CLOSE", ... "timestamp": datetime.datetime( 2025, 4, 3, 20, 0, 0, 130854, tzinfo=TzInfo(UTC) ), }, ... ] } }

- Updated the `AuctionSet` model to sort auction data by timestamp in ascending order before parsing. - Improved data integrity and consistency for auction data representation.

River-Shi · 2025-04-14T12:03:06Z

alpaca/data/models/auctions.py

@@ -86,10 +86,16 @@ def __init__(self, raw_data: RawData) -> None:
                                open_auction["at"] = "OPEN"
                        auction_data.extend(o)

-                parsed_auctions[symbol] = [
+                auction_data = [


add a sorted func to solve the issue

Thanks. What I thought was we already specifying order in the parameter. Therefore, just need to adjust the order of extend. but we realized we might want to adjust based on request.sort?

Discussed with the owner of the API endpoint and seems the sort parameter considering timestamp of each auction price. Therefore, I feel if asc, then extend open first. if desc, then extend close first might be enough?

Do you mean adding a parameter asc or desc? My thought is that we could let the user decide ascending or descending, so we can add a request parameter ascending: bool.

I meant sorting order should be aligned with users input (i.e. sort parameter of request (ref. default to asc)).
Current PR has sorting by ASC without considering users input.
The other point is that the response of API is already sorted by symbol and timestamp based on users input. Therefore, we could utilize response's sorted order by changing order of extend based on user's input?

- Modified the `AuctionSet` constructor to accept a `sort` parameter for auction data ordering. - Implemented conditional logic to sort auction data based on the specified sort order (ascending or descending). - Enhanced data integrity by ensuring auction data is parsed and ordered correctly before being stored.

River-Shi · 2025-04-15T10:40:31Z

alpaca/data/models/auctions.py

+                    if sort == Sort.DESC:
+                        if c is not None:
+                            for close_auction in c:
+                                if close_auction:
+                                    close_auction["at"] = "CLOSE"
+                            auction_data.extend(c)
+                        if o is not None:
+                            for open_auction in o:
+                                if open_auction:
+                                    open_auction["at"] = "OPEN"
+                            auction_data.extend(o)
+                    else:  # NOTE: None and ASC are the same
+                        if o is not None:
+                            for open_auction in o:
+                                if open_auction:
+                                    open_auction["at"] = "OPEN"
+                            auction_data.extend(o)
+                        if c is not None:
+                            for close_auction in c:
+                                if close_auction:
+                                    close_auction["at"] = "CLOSE"
+                            auction_data.extend(c)
+
+                parsed_auctions[symbol] = [


removed the sorting func and ustilize the asc/desc in requesting

Thank you! By the way, what is the meaning of if open_auction/if close_auction? Do you have observed something we need to handle the empty element? I felt we use for in the code, the element should have value?

hiohiohio

Overall LGTM! Left small comments.

hiohiohio · 2025-04-17T01:02:12Z

alpaca/data/models/auctions.py

+
+    data: Dict[str, List[Auction]] = {}
+
+    def __init__(self, raw_data: RawData, sort: Sort) -> None:


StockAuctionsRequest.sort is Optional[Sort]

Suggested change

def __init__(self, raw_data: RawData, sort: Sort) -> None:

def __init__(self, raw_data: RawData, sort: Optional[Sort]) -> None:

hiohiohio · 2025-04-17T01:02:34Z

alpaca/data/models/auctions.py

@@ -0,0 +1,108 @@
+from datetime import datetime
+from typing import Dict, List


to use Optional

Suggested change

from typing import Dict, List

from typing import Dict, List, Optional

hiohiohio · 2025-04-17T01:03:01Z

alpaca/data/models/auctions.py

+
+        Args:
+            raw_data (RawData): The collection of raw auction data from API keyed by Symbol.
+            sort (Sort): The sort order of the auctions.


Suggested change

sort (Sort): The sort order of the auctions.

sort (Optional[Sort]): The sort order of the auctions. Default to ASC

hiohiohio · 2025-04-17T01:04:35Z

alpaca/data/models/auctions.py

+                    if sort == Sort.DESC:
+                        if c is not None:
+                            for close_auction in c:
+                                if close_auction:


could we remove this if condition? or do we have possiblity to have None element in the list?

hiohiohio · 2025-04-17T01:28:05Z

alpaca/data/models/auctions.py

+                    c = auction.get("c")
+                    o = auction.get("o")
+
+                    if sort == Sort.DESC:
+                        if c is not None:
+                            for close_auction in c:
+                                if close_auction:
+                                    close_auction["at"] = "CLOSE"
+                            auction_data.extend(c)
+                        if o is not None:
+                            for open_auction in o:
+                                if open_auction:
+                                    open_auction["at"] = "OPEN"
+                            auction_data.extend(o)
+                    else:  # NOTE: None and ASC are the same
+                        if o is not None:
+                            for open_auction in o:
+                                if open_auction:
+                                    open_auction["at"] = "OPEN"
+                            auction_data.extend(o)
+                        if c is not None:
+                            for close_auction in c:
+                                if close_auction:
+                                    close_auction["at"] = "CLOSE"
+                            auction_data.extend(c)


How about below logic? tried to use .get("c", []) but it does not work for me.

Suggested change

c = auction.get("c")

o = auction.get("o")

if sort == Sort.DESC:

if c is not None:

for close_auction in c:

if close_auction:

close_auction["at"] = "CLOSE"

auction_data.extend(c)

if o is not None:

for open_auction in o:

if open_auction:

open_auction["at"] = "OPEN"

auction_data.extend(o)

else: # NOTE: None and ASC are the same

if o is not None:

for open_auction in o:

if open_auction:

open_auction["at"] = "OPEN"

auction_data.extend(o)

if c is not None:

for close_auction in c:

if close_auction:

close_auction["at"] = "CLOSE"

auction_data.extend(c)

c = auction.get("c")

if c is None:

c = []

o = auction.get("o")

if o is None:

o = []

for close_auction in c:

close_auction["at"] = "CLOSE"

for open_auction in o:

open_auction["at"] = "OPEN"

if sort == Sort.DESC:

auction_data.extend(c)

auction_data.extend(o)

else: # NOTE: None and ASC are the same

auction_data.extend(o)

auction_data.extend(c)

.get

I think both are fine. c = [] if c is None else c or .get("c", [])

Thanks. Yeah, somehow, .get("c", []) does not work for me. checking with below snippets.

from datetime import datetime from zoneinfo import ZoneInfo from alpaca.common.enums import Sort from alpaca.data.historical.stock import StockAuctionsRequest, StockHistoricalDataClient api_key="API KEY" secret_key="SECRET" client = StockHistoricalDataClient(api_key, secret_key) req = StockAuctionsRequest( symbol_or_symbols=["SPY"], start=datetime(2025, 4,2), end=datetime(2025, 4, 9, tzinfo=ZoneInfo("America/New_York")), sort=Sort.DESC, ) ret = client.get_stock_auctions(req)

hiohiohio · 2025-04-17T02:33:10Z

alpaca/data/historical/stock.py

+        raw_auctions = self._get_marketdata(
+            path="/stocks/auctions",
+            params=request_params.to_request_fields(),
+        )


We have recently introduced page_size parameter to _get_marketdata() [1], could you please set page_size for auctions as well?

*1 #583

Suggested change

raw_auctions = self._get_marketdata(

path="/stocks/auctions",

params=request_params.to_request_fields(),

)

raw_auctions = self._get_marketdata(

path="/stocks/auctions",

params=request_params.to_request_fields(),

page_limit = 1_000,

page_size = 1_000,

)

River-Shi requested a review from hiohiohio as a code owner April 8, 2025 14:06

hiohiohio requested a review from gnvk April 8, 2025 15:02

hiohiohio reviewed Apr 12, 2025

View reviewed changes

River-Shi requested a review from hiohiohio April 13, 2025 01:40

hiohiohio reviewed Apr 14, 2025

View reviewed changes

fix: Sort auction data by timestamp in AuctionSet model

fd114da

- Updated the `AuctionSet` model to sort auction data by timestamp in ascending order before parsing. - Improved data integrity and consistency for auction data representation.

This comment was marked as duplicate.

Sign in to view

River-Shi commented Apr 14, 2025

View reviewed changes

River-Shi commented Apr 15, 2025

View reviewed changes

hiohiohio reviewed Apr 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add auction data handling to stock historical data client #576

feat: Add auction data handling to stock historical data client #576

River-Shi commented Apr 8, 2025

River-Shi commented Apr 9, 2025

hiohiohio left a comment

hiohiohio Apr 12, 2025

hiohiohio Apr 12, 2025

hiohiohio Apr 12, 2025

hiohiohio Apr 12, 2025

River-Shi Apr 12, 2025

hiohiohio left a comment

hiohiohio Apr 14, 2025

River-Shi Apr 14, 2025

hiohiohio Apr 14, 2025 •

edited

Loading

River-Shi Apr 14, 2025

hiohiohio Apr 14, 2025

River-Shi Apr 14, 2025

This comment was marked as duplicate.

River-Shi Apr 14, 2025

hiohiohio Apr 15, 2025

hiohiohio Apr 15, 2025

River-Shi Apr 15, 2025

hiohiohio Apr 15, 2025 •

edited

Loading

River-Shi Apr 15, 2025

River-Shi Apr 15, 2025

hiohiohio Apr 17, 2025 •

edited

Loading

hiohiohio left a comment

hiohiohio Apr 17, 2025

hiohiohio Apr 17, 2025

hiohiohio Apr 17, 2025

hiohiohio Apr 17, 2025

hiohiohio Apr 17, 2025 •

edited

Loading

River-Shi Apr 17, 2025

hiohiohio Apr 17, 2025

hiohiohio Apr 17, 2025

	def get_stock_auction(self, request_params: StockAuctionsRequest):
	def get_stock_auctions(self, request_params: StockAuctionsRequest):

		# ############################## Auctions ################################# #


		class StockAuctionsRequest(BaseTimeseriesDataRequest):


		data: Dict[str, List[Auction]] = {}

		def __init__(self, raw_data: RawData, sort: Sort) -> None:

		@@ -0,0 +1,108 @@
		from datetime import datetime
		from typing import Dict, List

	from typing import Dict, List
	from typing import Dict, List, Optional

	sort (Sort): The sort order of the auctions.
	sort (Optional[Sort]): The sort order of the auctions. Default to ASC

feat: Add auction data handling to stock historical data client #576

Are you sure you want to change the base?

feat: Add auction data handling to stock historical data client #576

Conversation

River-Shi commented Apr 8, 2025

River-Shi commented Apr 9, 2025

hiohiohio left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiohiohio left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiohiohio Apr 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as duplicate.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiohiohio Apr 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiohiohio Apr 17, 2025 • edited Loading

Choose a reason for hiding this comment

hiohiohio left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiohiohio Apr 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiohiohio Apr 14, 2025 •

edited

Loading

hiohiohio Apr 15, 2025 •

edited

Loading

hiohiohio Apr 17, 2025 •

edited

Loading

hiohiohio Apr 17, 2025 •

edited

Loading