Mirror Account Chart onto CashCtrl

[lasuk]

Objective

Extend the CashCtrlLedger class to synchronize remote CashCtrl accounts with a target account chart in pyledger format.

Detailed Description

Create a method named mirror_account_chart() within the CashCtrlLedger class to synchronize a target account chart, specified as a DataFrame in the pyledger.account_chart() column schema, onto a remote CashCtrl instance. This method will handle the addition of new accounts, updates to existing accounts, and optionally, the deletion of accounts not present in the target DataFrame.

class CashCtrlLedger(LedgerEngine):

    def mirror_account_chart(self, target: pd.DataFrame, delete: bool = True):
        """
        Synchronizes remote CashCtrl accounts with a desired target state provided as a DataFrame.
        Args:
            target (pd.DataFrame): DataFrame with an account chart in the pyledger format.
            delete (bool, optional): If True, deletes accounts on the remote that are not present in the target DataFrame.
        """

Field mapping between pyledger (left) and CashCtrl (right) includes:

• 'account' (int) -> 'number' (unique identifier)
• 'currency' (str) -> 'currencyCode'
• 'text' (str) -> 'name'
• 'vat_code' (str | pd.NA) -> Look up tax['name'] via 'taxId'
• 'group' (str | pd.NA) -> path

Accounts are uniquely identified by an account number (field 'account' in pyledger, corresponds to field 'number' in CashCtrl).

Tasks

1. Schema Extension

   • Extend the LedgerEngine.OPTIONAL_ACCOUNT_COLUMNS schema to include 'group' as an additional column.

2. Accessor and Mutator Methods

   • Implement a method to retrieve the current account chart from CashCtrl in pyledger DataFrame format.

     def account_chart(self) -> pd.DataFrame:
      """Retrieves the account chart from a remote CashCtrl instance, formatted to the pyledger schema."""

   • Develop methods for adding, updating, and deleting accounts based on the pyledger data.

     def add_account(self, account: str, currency: str, text: str, vat_code: str | None = None, group: str | None = None):
      """Adds a new account to the remote CashCtrl instance."""
     
     def update_account(self, account: str, currency: str, text: str, vat_code: str | None = None, group: str | None = None):
      """Updates an existing account in the remote CashCtrl instance."""
     
     def delete_account(self, account: str):
      """Deletes an account from the remote CashCtrl instance."""

   • Write unit tests for these methods.

3. Implementation of mirror_account_chart()

   • Ensure the target account chart conforms to the expected schema: target = StandaloneLedger.standardize_account_chart(target).
   • Retrieve current accounts from CashCtrl: remote = self.account_chart()
   • Use set operations on the 'account' field (the unique identifier), find accounts 'to_add', 'to_delete', 'to_keep'.
   • Employ mutator methods to synchronize the remote CashCtrl accounts with the target state.
   • Extend unit tests to cover the mirror_account_chart() method, include scenarios where the target DataFrame is empty, contains NA vat_code, or where vat_codes are not defined.

4. Submit Pull Request

   • Submit the changes for review, assigning the PR to Lukas.

Test Data

The CashCtrl test account is pre-populated with a standard Swiss PME account chart.

• Save the initial CashCtrl account chart in CashCtrl schema as CSV files as backup:

  cc_client = CashCtrlClient()
  df = cc_client.list_accounts()
  df.to_csv('default_cashctrl_accounts.csv')

• Save the remote account chart in pyledger format for testing purposes:

  ledger = CashCtrlLedger()
  df = ledger.account_chart()
  df.to_csv('account_chart.csv')