py_alpaca_api.trading.watchlists

Exceptions

ValidationError

Raised when input validation fails.

Classes

Requests

WatchlistModel

Watchlist

Functions

watchlist_class_from_dict(→ WatchlistModel)

param data_dict:

A dictionary containing the data needed to create a WatchlistModel object.

Module Contents

exception py_alpaca_api.trading.watchlists.ValidationError[source]

Bases: PyAlpacaAPIError

Raised when input validation fails.

class py_alpaca_api.trading.watchlists.Requests[source]
request(method: str, url: str, headers: dict[str, str] | None = None, params: dict[str, str | bool | float | int] | None = None, json: dict[str, Any] | None = None, raw_response: bool = False)[source]

Execute HTTP request with retry logic.

Parameters:

  • method – A string representing the HTTP method to be used in the request.

  • url – A string representing the URL to send the request to.

  • headers – An optional dictionary containing the headers for the request.

  • params – An optional dictionary containing the query parameters for the request.

  • json – An optional dictionary containing the JSON payload for the request.

  • raw_response – If True, return the raw response object without status checks. Defaults to False.

Returns:

The response object returned by the server.

Raises:

APIRequestError – If the response status code is not one of the acceptable statuses (200, 204, 207) and raw_response is False.

class py_alpaca_api.trading.watchlists.WatchlistModel[source]
id: str
account_id: str
created_at: datetime.datetime
updated_at: datetime.datetime
name: str
assets: list[py_alpaca_api.models.asset_model.AssetModel]
py_alpaca_api.trading.watchlists.watchlist_class_from_dict(data_dict: dict) → WatchlistModel[source]
Parameters:

data_dict – A dictionary containing the data needed to create a WatchlistModel object.

Returns:

A new instance of the WatchlistModel created from the data in the input dictionary.

class py_alpaca_api.trading.watchlists.Watchlist(base_url: str, headers: dict[str, str])[source]
get(watchlist_id: str | None = None, watchlist_name: str | None = None) → py_alpaca_api.models.watchlist_model.WatchlistModel | str[source]

Retrieves a watchlist based on the provided watchlist ID or name.

Parameters:

  • watchlist_id (str, optional) – The ID of the watchlist to retrieve.

  • watchlist_name (str, optional) – The name of the watchlist to retrieve.

Returns:

The retrieved watchlist.

Return type:

WatchlistModel

Raises:

ValueError – If both watchlist_id and watchlist_name are provided, or if neither is provided.

get_all() → list[py_alpaca_api.models.watchlist_model.WatchlistModel | str][source]

Retrieves all watchlists.

Returns:

A list of WatchlistModel objects representing all the watchlists.

Raises:

Exception – If the API request fails.

create(name: str, symbols: list | str | None = None) → py_alpaca_api.models.watchlist_model.WatchlistModel | str[source]

Creates a new watchlist with the given name and symbols.

Parameters:

  • name (str) – The name of the watchlist.

  • symbols (str, optional) – A comma-separated string of symbols to add to the watchlist. Defaults to “”.

Returns:

The created watchlist.

Return type:

WatchlistModel

Raises:

SomeException – An exception that may occur during the request.

update(watchlist_id: str | None = None, watchlist_name: str | None = None, name: str = '', symbols: list | str | None = None) → py_alpaca_api.models.watchlist_model.WatchlistModel | str[source]

Update a watchlist with the specified parameters.

Parameters:

  • watchlist_id (str, optional) – The ID of the watchlist to update. Either watchlist_id or watchlist_name

  • provided. (watchlist_name must be)

  • watchlist_name (str, optional) – The name of the watchlist to update. Either watchlist_id or

  • provided.

  • name (str, optional) – The new name for the watchlist. If not provided, the existing name will be used.

  • symbols (str, optional) – A comma-separated string of symbols to update the watchlist with. If not provided, the existing symbols

  • used. (will be)

Returns:

The updated watchlist.

Return type:

WatchlistModel

Raises:

  • ValueError – If both watchlist_id and watchlist_name are provided, or if neither watchlist_id nor

  • watchlist_name –

delete(watchlist_id: str | None = None, watchlist_name: str | None = None) → str[source]

Deletes a watchlist.

Parameters:

  • watchlist_id (str, optional) – The ID of the watchlist to delete.

  • watchlist_name (str, optional) – The name of the watchlist to delete.

Returns:

A message indicating the successful deletion of the watchlist.

Return type:

str

Raises:

ValueError – If both watchlist_id and watchlist_name are provided or if neither is provided.

add_asset(watchlist_id: str | None = None, watchlist_name: str | None = None, symbol: str = '') → py_alpaca_api.models.watchlist_model.WatchlistModel | str[source]

Adds an asset to a watchlist.

Parameters:

  • watchlist_id (str) – The ID of the watchlist to add the asset to. If watchlist_id is provided,

  • None. (watchlist_id should be)

  • watchlist_name (str) – The name of the watchlist to add the asset to. If watchlist_name is provided,

  • None.

  • symbol (str) – The symbol of the asset to add to the watchlist.

Returns:

The updated watchlist after adding the asset.

Return type:

WatchlistModel

Raises:

  • ValueError – If both watchlist_id and watchlist_name are provided or neither is provided.

  • ValueError – If symbol is not provided.

remove_asset(watchlist_id: str | None = None, watchlist_name: str | None = None, symbol: str = '') → py_alpaca_api.models.watchlist_model.WatchlistModel | str[source]

Removes an asset from a watchlist.

Parameters:

  • watchlist_id (str, optional) – The ID of the watchlist. If not provided, the watchlist_name parameter

  • to (will be used)

  • None. (retrieve the ID. Defaults to)

  • watchlist_name (str, optional) – The name of the watchlist. If not provided, thewatchlist_id parameter will be used to

  • None.

  • symbol (str) – The symbol of the asset to be removed from the watchlist.

Returns:

The updated watchlist object.

Return type:

WatchlistModel

Raises:

ValueError – If both watchlist_id and watchlist_name are provided, or if symbol is not provided.

get_assets(watchlist_id: str | None = None, watchlist_name: str | None = None) → list[source]

Retrieves the symbols of assets in a watchlist.

Parameters:

  • watchlist_id (str, optional) – The ID of the watchlist. Either watchlist_id or watchlist_name should be provided,

  • None. (not both. Defaults to)

  • watchlist_name (str, optional) – The name of the watchlist. Either watchlist_id or watchlist_name should be

  • provided

  • None.

Returns:

A list of symbols of assets in the watchlist.

Return type:

list

Raises:

  • ValueError – If both watchlist_id and watchlist_name are provided, or if neither watchlist_id nor

  • watchlist_name –