Get tenders from Square, optionally from a specific location and/or time.

get_square_tenders.py

"""
The star of this show is get_tenders, which will return all tenders
if there are no keyword arguments supplied, or tenders from a specific location,
and/or before/after datetimes.

For convenience, here are the fields of a Tender:

    'id'
    'location_id'
    'transaction_id'
    'created_at'
    'note'
    'amount_money'
    'tip_money'
    'processing_fee_money'
    'customer_id'
    'type'
    'card_details'
    'cash_details'
    'additional_recipients'

requires squareconnect (https://github.com/square/connect-python-sdk) and Python 3.5+
"""

import datetime
from typing import Dict, Union, List

import squareconnect
from squareconnect.apis.locations_api import LocationsApi
from squareconnect.apis.transactions_api import TransactionsApi
from squareconnect.models.tender import Tender
from squareconnect.models.transaction import Transaction

SQUARE_TOKEN_SANDBOX = 'put your token here'
squareconnect.configuration.access_token = SQUARE_TOKEN_SANDBOX


def get_location_name_id_dict() -> Union[dict, Dict[str, str]]:
    """dictionary keys are the first word/number in the location's address"""
    l = LocationsApi()
    locations = l.list_locations().locations
    if len(locations) == 0:
        return {}

    return {location.address.address_line_1.split(' ')[0]: location.id
            for location in locations}


def extract_tenders(transactions: Union[list, List[Transaction]]
                    ) -> Union[list, List[Tender]]:
    if len(transactions) == 0:
        return []

    return [tender
            for transaction in transactions
            for tender in transaction.tenders]


def get_kwargs(before: datetime.datetime,
               after: datetime.datetime
               ) -> Union[dict, Dict[Union[None, str], Union[None, str]]]:
    kwargs = {}

    if after is not None:
        if after.tzinfo is None:
            after = after.replace(tzinfo=datetime.timezone.utc)
        kwargs['begin_time'] = after.isoformat()

    if before is not None:
        if before.tzinfo is None:
            before = before.replace(tzinfo=datetime.timezone.utc)
        kwargs['end_time'] = before.isoformat()
        if 'begin_time' not in kwargs:
            kwargs['begin_time'] = before - datetime.timedelta(days=30)

    return kwargs


def get_location_ids(loc_str: Union[None, str]
                     ) -> List[str]:
    location_dict = get_location_name_id_dict()

    if loc_str is None:
        return list(location_dict.values())

    if loc_str in location_dict.values():
        location_id = loc_str
    else:
        location_id = location_dict.get(loc_str)
        if location_id is None:
            raise Exception(f'{loc_str} isn\'t valid.')

    return [location_id]


def get_tenders(loc_str: str = None,
                before: datetime.datetime = None,
                after: datetime.datetime = None,
                ) -> Union[list, List[Tender]]:
    """The loc_str can be a location_id or the first word/number in a location's address."""

    location_ids = get_location_ids(loc_str)

    kwargs = get_kwargs(before, after)

    t = TransactionsApi()
    transactions = []

    for location_id in location_ids:
        transactions_for_loc_id = t.list_transactions(location_id=location_id,
                                                      **kwargs).transactions
        if transactions_for_loc_id is not None:
            transactions += transactions_for_loc_id

    return extract_tenders(transactions)