Transactions¶

niveshpy transactions¶

Wrapper group for transaction-related commands.

Usage:

niveshpy transactions [options] <command>

Options:

  -h, --help  Show this message and exit.

Subcommands

add: Create a new transaction.
delete: Delete a transaction based on a query.
list: List all transactions.

niveshpy transactions add¶

Create a new transaction.

To create transactions interactively, run niveshpy transactions add without any arguments.

To add a transaction non-interactively, provide all required arguments along with an optional --no-input flag.

Arguments: transaction_date : Date of the transaction in YYYY-MM-DD format. transaction_type : Type of the transaction (either "purchase" or "sale"). description : Description of the transaction. amount : Amount of money involved in the transaction. units : Number of units involved in the transaction. account_id : ID of the account associated with the transaction. security_key : Key of the security involved in the transaction.

Usage:

niveshpy transactions add [options] [<transaction_date>] [<transaction_type>]
                          [<description>] [<amount>] [<units>] [<account_id>]
                          [<security_key>]

Options:

  --no-input  Run without user input, using defaults or skipping prompts.
  -h, --help  Show this message and exit.

niveshpy transactions delete¶

Delete a transaction based on a query.

If no key is provided, you will be prompted to select from existing transactions. The query will be used to search for transactions by ID first. If no exact match is found, a text search will be performed based on various attributes. If multiple transactions match the provided query, you will be prompted to select one.

Associated accounts and securities will not be deleted.

When running in a non-interactive mode, --force must be provided to confirm deletion. Additionally, the must match exactly one transaction ID.

Usage:

niveshpy transactions delete [options] [<queries>]

Options:

  -l, --limit INTEGER  Maximum number of limit to list.  [default: 100]
  --no-input           Run without user input, using defaults or skipping
                       prompts.
  -f, --force          Force the operation without confirmation.
  -n, --dry-run        Simulate the operation without making any changes.
  -h, --help           Show this message and exit.

niveshpy transactions list¶

List all transactions.

Optionally provide a text QUERY to filter transactions by various attributes.

View the documentation at https://yashovardhan99.github.io/niveshpy/cli/transactions/ for examples.

Usage:

niveshpy transactions list [options] [<queries>]

Options:

  -l, --limit INTEGER  Maximum number of accounts to list.  [default: 30]
  --offset INTEGER     Number of accounts to skip before starting to list. Use
                       with --limit for pagination.  [default: 0]
  --json
  --csv
  -h, --help           Show this message and exit.

Usage notes and examples¶

List transactions¶

Example

niveshpy transactions
niveshpy transactions list gold # (1)
niveshpy transactions list acct:Z123 # (2)
niveshpy transactions list type:purchase # (3)

Filter by a security with 'gold' in its name or key.
Filter by account 'Z123'.
Filter by transaction type 'purchase'

Model Reference¶

Models for financial transactions.

Transaction ¶

Bases: TransactionBase

Database model for transactions.

Attributes:

Name	Type	Description
`id`	`int \| None`	Primary key ID of the transaction. None if not yet stored in DB.
`transaction_date`	`date`	Date of the transaction.
`type`	`TransactionType`	Type of the transaction.
`description`	`str`	Description of the transaction.
`amount`	`Decimal`	Amount involved in the transaction.
`units`	`Decimal`	Number of units involved in the transaction.
`security_key`	`str`	Foreign key to the associated security.
`security`	`Security`	Related security object.
`account_id`	`int`	Foreign key to the associated account.
`account`	`Account`	Related account object.
`properties`	`dict[str, Any]`	Additional properties of the transaction.
`created`	`datetime`	Timestamp when the transaction was created.

TransactionBase ¶

Bases: SQLModel

Base model for transactions.

Attributes:

Name	Type	Description
`transaction_date`	`date`	Date of the transaction.
`type`	`TransactionType`	Type of the transaction.
`description`	`str`	Description of the transaction.
`amount`	`Decimal`	Amount involved in the transaction.
`units`	`Decimal`	Number of units involved in the transaction.
`security_key`	`str`	Foreign key to the associated security.
`account_id`	`int`	Foreign key to the associated account.
`properties`	`dict[str, Any]`	Additional properties of the transaction. Defaults to an empty dictionary.

__init_subclass__ ¶

__init_subclass__(**kwargs)

Ensure subclasses are properly initialized.

Source code in niveshpy/models/transaction.py

def __init_subclass__(cls, **kwargs):
    """Ensure subclasses are properly initialized."""
    return super().__init_subclass__(**kwargs)

TransactionCreate ¶

Bases: TransactionBase

Model for creating transactions.

Attributes:

Name	Type	Description
`transaction_date`	`date`	Date of the transaction.
`type`	`TransactionType`	Type of the transaction.
`description`	`str`	Description of the transaction.
`amount`	`Decimal`	Amount involved in the transaction.
`units`	`Decimal`	Number of units involved in the transaction.
`security_key`	`str`	Foreign key to the associated security.
`account_id`	`int`	Foreign key to the associated account.
`properties`	`dict[str, Any]`	Additional properties of the transaction. Defaults to an empty dictionary.

TransactionDisplay ¶

Bases: TransactionPublic

Model for displaying transaction with related info.

Attributes:

Name	Type	Description
`id`	`int`	Primary key ID of the transaction.
`transaction_date`	`date`	Date of the transaction.
`type`	`TransactionType`	Type of the transaction.
`description`	`str`	Description of the transaction.
`amount`	`Decimal`	Amount involved in the transaction.
`units`	`Decimal`	Number of units involved in the transaction.
`security`	`str`	Formatted security information.
`account`	`str`	Formatted account information.
`properties`	`dict[str, Any]`	Additional properties of the transaction.
`created`	`datetime`	Timestamp when the transaction was created.

validate_account `classmethod` ¶

validate_account(value: str | Account) -> str

Validate and format the account field.

Parameters:

Name	Type	Description	Default
`value`	`str \| Account`	The account value to format.	required

Returns:

Name	Type	Description
`str`	`str`	Formatted account string.

Source code in niveshpy/models/transaction.py

@field_validator("account", mode="before", json_schema_input_type=str | Account)
@classmethod
def validate_account(cls, value: str | Account) -> str:
    """Validate and format the account field.

    Args:
        value (str | Account): The account value to format.

    Returns:
        str: Formatted account string.
    """
    if isinstance(value, Account):
        return f"{value.name} ({value.institution})"
    return value

validate_security `classmethod` ¶

validate_security(value: str | Security) -> str

Validate and format the security field.

Parameters:

Name	Type	Description	Default
`value`	`str \| Security`	The security value to format.	required

Returns:

Name	Type	Description
`str`	`str`	Formatted security string.

Source code in niveshpy/models/transaction.py

@field_validator("security", mode="before", json_schema_input_type=str | Security)
@classmethod
def validate_security(cls, value: str | Security) -> str:
    """Validate and format the security field.

    Args:
        value (str | Security): The security value to format.

    Returns:
        str: Formatted security string.
    """
    if isinstance(value, Security):
        return f"{value.name} ({value.key})"
    return value

TransactionPublic ¶

Bases: TransactionBase

Public model for transactions.

Attributes:

Name	Type	Description
`id`	`int`	Primary key ID of the transaction.
`transaction_date`	`date`	Date of the transaction.
`type`	`TransactionType`	Type of the transaction.
`description`	`str`	Description of the transaction.
`amount`	`Decimal`	Amount involved in the transaction.
`units`	`Decimal`	Number of units involved in the transaction.
`security_key`	`str`	Foreign key to the associated security.
`account_id`	`int`	Foreign key to the associated account.
`properties`	`dict[str, Any]`	Additional properties of the transaction.
`created`	`datetime`	Timestamp when the transaction was created.

TransactionPublicWithRelations ¶

Bases: TransactionPublic

Public model for transactions with related account and security info.

Attributes:

Name	Type	Description
`id`	`int`	Primary key ID of the transaction.
`transaction_date`	`date`	Date of the transaction.
`type`	`TransactionType`	Type of the transaction.
`description`	`str`	Description of the transaction.
`amount`	`Decimal`	Amount involved in the transaction.
`units`	`Decimal`	Number of units involved in the transaction.
`security`	`Security`	Related security object.
`account`	`Account`	Related account object.
`properties`	`dict[str, Any]`	Additional properties of the transaction.
`created`	`datetime`	Timestamp when the transaction was created.

TransactionType ¶

Bases: StrEnum

Enum for transaction types.

PURCHASE `class-attribute` `instance-attribute` ¶

PURCHASE = auto()

Transaction type representing purchases.

This type indicates any amount spent on acquiring securities or assets. However, you may use it for other types of transactions as well.

SALE `class-attribute` `instance-attribute` ¶

SALE = auto()

Transaction type representing sales.

This type indicates any amount received from selling securities or assets. However, you may use it for other types of transactions as well.

Transactions¶

niveshpy transactions¶

niveshpy transactions add¶

niveshpy transactions delete¶

niveshpy transactions list¶

Usage notes and examples¶

List transactions¶

Model Reference¶

Transaction ¶

TransactionBase ¶

__init_subclass__ ¶

TransactionCreate ¶

TransactionDisplay ¶

validate_account classmethod ¶

validate_security classmethod ¶

TransactionPublic ¶

TransactionPublicWithRelations ¶

TransactionType ¶

PURCHASE class-attribute instance-attribute ¶

SALE class-attribute instance-attribute ¶

validate_account `classmethod` ¶

validate_security `classmethod` ¶

PURCHASE `class-attribute` `instance-attribute` ¶

SALE `class-attribute` `instance-attribute` ¶