Mirror VAT Rates onto CashCtrl

Objective

Extend the CashCtrlLedger class to include functionality that synchronize VAT rates in a remote CashCtrl account with a desired state specified as DataFrame in pyledger.vat format.

Detailed Description

Implement the mirror_vat_codes() method to align VAT rates in the remote CashCtrl account with a desired target_state DataFrame. This method will add, update, and optionally delete VAT codes based on the comparison between the current state of the remote accounts and the target state.

class CashCtrlLedger(LedgerEngine):

    def mirror_vat_codes(self, target_state: pd.DataFrame, delete: bool = True):
        """
        Aligns VAT rates on the remote CashCtrl account with the desired state provided as a DataFrame.

        Args:
            target_state (pd.DataFrame): DataFrame containing VAT rates in the pyledger.vat_codes format.
            delete (bool, optional): If True, deletes VAT codes on the remote account that are not present in the target_state DataFrame.
        """

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

'id' -> 'name'
'rate' -> 'percentage'
'inclusive' -> 'calcType'
'account' -> 'accountId'
'text' -> 'documentName'

VAT codes are identified by unique names (local 'id' / remote 'names') both in the desired state and on the remote system.

Tasks

Implement Accessor and Mutator Methods

Write a method to fetch VAT codes from the CashCtrl account, returning a DataFrame that matches the pyledger column schema. Use StandaloneLedger.standardize_vat_codes() to enforce this schema.
```
def get_vat_codes(self) -> pd.DataFrame:
   """Retrieves VAT codes from the CashCtrl account formatted to the pyledger schema."""
```

Implement methods to add, update, and delete VAT codes, ensuring data compatibility with the pyledger VAT code format:

def add_vat_code(self, code: str, rate: float, account: str, included: bool = True, date: datetime.date | None = None):
   """Adds a new VAT code to the CashCtrl account."""

def update_vat_code(self, code: str, rate: float, account: str, included: bool = True, date: datetime.date | None = None):
   """Updates an existing VAT code in the CashCtrl account."""

def delete_vat_code(self, code: str):
   """Deletes a VAT code from the CashCtrl account."""

Write unit tests for these methods.

Implementat mirror_vat_codes()
- Begin by invoking StandaloneLedger.standardize_vat_codes() to enforce the expected DataFrame schema on the target_state input data.
- Utilize Python set operations to identify VAT codes to add, keep, or delete. Determine which codes to keep require updates.
- Use mutator methods to align the remote CashCtrl account with the desired state.
- Extend the unit tests to cover mirror_vat_codes().
  - Include scenarios where the target_state DataFrame is empty or where the account_id does not exist in the account chart.
  - Refer to cashctrl_api/tests/test_mirror_directory.py for an example unit test for a mirror function.
This task offers a great opportunity for sharing experiences on directing ChatGPT in writing Python methods and tests. Oleksandr, please schedule a coding session with Lukas after completing step 1.
Submit Pull Request
- Submit the changes for review, assigning to Lukas.

Remarks

The function StandaloneLedger.standardize_vat_codes() does not align with the latest design ideas. We will refactor it later to enforce the DataFrame schema more strictly with the new enforce_column_types() function. Additionally, it should be moved from the StandaloneLedger to the LedgerEngine class. These refactoring steps are outside of the scope of the current milestone.
It could be helpful to save CashCtrl as a csv file before making any changes on the remote side.

Test data

Example VAT codes in csv format:

id, account, rate, inclusive, text
Exempt,       , 0.0,    True, Exempt from VAT
OutStd,   2200, 0.077,  True, VAT at the regular 7.7% rate on goods or services sold
OutRed,   2200, 0.025,  True, VAT at the reduced 2.5% rate on goods or services sold
OutAcc,   2200, 0.037,  True, VAT at the 2.5% accommodation rate on goods or services sold
OutStdEx, 2200, 0.077, False, VAT at the regular 7.7% rate on goods or services sold
InStd,    1170, 0.077,  True, Input Tax (Vorsteuer) at the regular 7.7% rate on purchased goods or services
InRed,    1170, 0.025,  True, Input Tax (Vorsteuer) at the reduced 2.5% rate on purchased goods or services
InAcc,    1170, 0.037,  True, Input Tax (Vorsteuer) at the 3.7% accommodation rate on purchased goods or services

macxred / cashctrl_ledger