Securities Entity¶

The Securities entity is a typed list of Security objects. It is the standard container used to hold a portfolio's positions and provides methods for validation, transformation, and comparison.

from everysk.sdk.entities.portfolio.securities import Securities

Creating a Securities Collection¶

Pass a list of dictionaries or Security objects:

securities = Securities([
    {'symbol': 'AAPL', 'quantity': 100.0},
    {'symbol': 'GOOGL', 'quantity': 50.0},
])

len(securities)
# 2

type(securities[0])
# <class 'everysk.sdk.entities.portfolio.security.Security'>

Validate¶

The validate() method checks that the collection is not empty and that every Security inside it has all required fields. It auto-generates the id field for any security that is missing one:

securities = Securities([
    {'symbol': 'AAPL', 'quantity': 100.0},
    {'symbol': 'GOOGL', 'quantity': 50.0},
])
securities.validate()
# True

Calling validate() on an empty collection raises a FieldValueError:

Securities().validate()
# FieldValueError: The quantity of securities cannot be zero.

Remove Errors¶

The remove_errors() method returns a new Securities collection containing only positions whose status is not 'ERROR':

securities = Securities([
    {'symbol': 'AAPL', 'quantity': 100.0, 'status': 'OK'},
    {'symbol': 'GOOGL', 'quantity': 50.0, 'status': 'ERROR'},
    {'symbol': 'MSFT', 'quantity': 75.0, 'status': 'OK'},
])

clean = securities.remove_errors()
len(clean)
# 2

Create from Lists¶

The from_lists() static method builds a Securities collection from a list-of-lists where the first row is the header:

data = [
    ['symbol', 'quantity', 'market_price'],
    ['AAPL', 100.0, 150.0],
    ['GOOGL', 50.0, 2800.0],
]

securities = Securities.from_lists(data)
len(securities)
# 2

securities[0].symbol
# 'AAPL'

Convert to Lists¶

The to_lists() method is the inverse of from_lists(). It returns a list-of-lists with the header as the first row:

securities = Securities([
    {'symbol': 'AAPL', 'quantity': 100.0},
    {'symbol': 'GOOGL', 'quantity': 50.0},
])

rows = securities.to_lists()
len(rows)
# 3  (header + 2 securities)

rows[0]
# ['symbol', 'quantity', ...]  (header row, ordered by sort_header)

A custom header can be passed to control the column order:

rows = securities.to_lists(header=['symbol', 'quantity'])
rows[0]
# ['symbol', 'quantity']

rows[1]
# ['AAPL', 100.0]

Convert to a List of Dicts¶

The to_list() method converts each Security to a plain dictionary and returns them as a list:

securities = Securities([
    {'symbol': 'AAPL', 'quantity': 100.0},
    {'symbol': 'GOOGL', 'quantity': 50.0},
])

dicts = securities.to_list()
len(dicts)
# 2

dicts[0]['symbol']
# 'AAPL'

Diff¶

The diff() static method compares two securities lists and returns a breakdown of the changes. By default it uses the comparable field as the comparison key:

securities_a = [{'symbol': 'AAPL', 'quantity': 100.0, 'comparable': 'AAPL'}]
securities_b = [{'symbol': 'AAPL', 'quantity': 120.0, 'comparable': 'AAPL'},
                {'symbol': 'MSFT', 'quantity': 50.0, 'comparable': 'MSFT'}]

result = Securities.diff(securities_a, securities_b)
# {
#     'added_positions': [...],
#     'removed_positions': [...],
#     'partial_positions': [...],
#     'equal_positions': [...],
# }

A custom accessor field can be specified:

result = Securities.diff(securities_a, securities_b, accessor='symbol')

Consolidate¶

The consolidate() method merges positions that share the same values for the given keys, summing their quantities:

securities = Securities([
    {'symbol': 'AAPL', 'quantity': 100.0, 'exchange': 'NASDAQ'},
    {'symbol': 'AAPL', 'quantity': 50.0, 'exchange': 'NASDAQ'},
    {'symbol': 'GOOGL', 'quantity': 75.0, 'exchange': 'NASDAQ'},
])

consolidated = securities.consolidate(['symbol', 'exchange'])
# Returns a new Securities with AAPL consolidated into one position