Security Entity¶

The Security entity represents a single financial instrument inside a portfolio. It behaves both as a dictionary and as an SDK entity, meaning you can access its fields by attribute name or by key.

from everysk.sdk.entities.portfolio.security import Security

Attributes¶

Below are the main attributes of the Security entity:

status: The status of the security (e.g. 'OK', 'DELISTED', 'ERROR').
id: The unique identifier of the security. Auto-generated if not provided.
symbol: The symbol of the security (e.g. 'AAPL').
quantity: The quantity held.
instrument_class: The class of the instrument (e.g. 'Equity').
ticker: The ticker symbol.
label: A short label for display purposes.
name: The full name of the security (e.g. 'Apple Inc.').
isin: The ISIN (International Securities Identification Number).
exchange: The exchange where the security is traded.
currency: The currency of the security (e.g. 'USD').
fx_rate: The foreign exchange rate.
market_price: The current market price.
market_value: The market value (quantity × market_price).
market_value_in_base: The market value in the portfolio base currency.
instrument_type / instrument_subtype: Type and subtype of the instrument.
asset_class / asset_subclass: Asset classification.
maturity_date: The maturity date (stored as 'YYYYMMDD' string).
issue_date: The issue date (stored as 'YYYYMMDD' string).
return_date: The return date (stored as 'YYYYMMDD' string).
settlement: The settlement date (stored as 'YYYYMMDD' string).
cost_price: The cost price.
unrealized_pl / unrealized_pl_in_base: Unrealized profit or loss.
extra_data: A dictionary for any additional fields that do not map to standard attributes.

Unknown keyword arguments passed at construction time are automatically stored in extra_data.

Creating a Security¶

security = Security(
    symbol='AAPL',
    quantity=100.0,
    market_price=150.0,
    currency='USD',
    name='Apple Inc.',
    status='OK',
)

security.symbol
# 'AAPL'

security.quantity
# 100.0

Extra Data¶

Any attribute that does not correspond to a known field is automatically moved to extra_data:

security = Security(symbol='AAPL', quantity=50.0, industry='Technology')

security.extra_data
# {'industry': 'Technology'}

You can also provide extra data explicitly:

security = Security(
    symbol='AAPL',
    quantity=50.0,
    extra_data={'industry': 'Technology', 'country': 'USA'},
)

security.extra_data
# {'industry': 'Technology', 'country': 'USA'}

Generate a Security ID¶

The generate_security_id() static method creates a unique security ID with a standard prefix:

Security.generate_security_id()
# 'sec_p06No4'

Security.generate_security_id()
# 'sec_OxvW5r'

Each call returns a different value. If a Security object is validated without an id, one is auto-generated.

Validate Required Fields¶

The validate_required_fields() method checks that all mandatory fields (symbol, quantity, id) are present. If id is missing it is auto-generated:

security = Security(symbol='AAPL', quantity=100.0)
security.validate_required_fields()
# True

security.id
# 'sec_p06No4'  (auto-generated)

Get Attribute¶

The _get_attr() static method retrieves a value from a security dictionary, also looking inside extra_data when the key is not a top-level field. An optional fallback callable is called if the key is not found anywhere:

security = Security(symbol='AAPL', quantity=100.0, industry='Technology')

Security._get_attr(security, 'symbol')
# 'AAPL'

Security._get_attr(security, 'industry')
# 'Technology'

Security._get_attr(security, 'missing_key')
# None

Security._get_attr(security, 'missing_key', lambda: 'default_val')
# 'default_val'

Generate Consolidation Key¶

The generate_consolidation_key() method builds a single string key from one or more attribute values, used to group or deduplicate securities:

security = Security(symbol='AAPL', quantity=100.0, instrument_class='Equity')
security.generate_consolidation_key(['symbol', 'instrument_class'])
# 'AAPL_Equity'

If a specified attribute is missing, a new security ID is generated as a fallback to ensure uniqueness.

Sort Header¶

The sort_header() static method reorders a list of attribute names according to the platform's canonical column order. Unrecognised keys are appended alphabetically at the end:

Security.sort_header(['symbol', 'name', 'quantity', 'instrument_class'])
# ['symbol', 'quantity', 'instrument_class', 'name']

Create from a List¶

The from_list() static method constructs a Security from a flat list of values and a matching list of header names:

security = Security.from_list(
    ['AAPL', 100.0, 150.0],
    ['symbol', 'quantity', 'market_price'],
)

security.symbol
# 'AAPL'

security.market_price
# 150.0

Convert to a List¶

The to_list() method serializes the security back to a flat list of values. The column order follows sort_header() by default, or a custom header can be provided:

security = Security(symbol='AAPL', quantity=100.0, market_price=150.0)
security.to_list(header=['symbol', 'quantity', 'market_price'])
# ['AAPL', 100.0, 150.0]