From 4b20005b50f33ea5f410eb43e49fcb1dc7ece16d Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Mon, 3 Dec 2018 20:20:17 +0100 Subject: [PATCH] Rename get_data/set_data to deconstruct/from_data --- docs/client.rst | 12 ++++++------ docs/tans.rst | 4 ++-- fints/client.py | 29 +++++++++++++++-------------- tests/test_client.py | 4 ++-- 4 files changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/client.rst b/docs/client.rst index 9253c38..481b7c3 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -14,18 +14,18 @@ across invocations. This includes * The User Parameter Data (UPD) with information about the user account and allowed actions .. autoclass:: fints.client.FinTS3Client - :members: __init__, get_data, set_data + :members: __init__, deconstruct, set_data :noindex: :undoc-members: -Using the :func:`~fints.client.FinTS3Client.get_data`/:func:`~fints.client.FinTS3Client.set_data` +Using the :func:`~fints.client.FinTS3Client.deconstruct`/:func:`~fints.client.FinTS3Client.set_data` facility is purely optional for reading operations, but may speed up the process because the BPD/UPD can be cached and need not be transmitted again. It may be required to use the facility for transaction operations if both parts of a two-step transaction cannot be completed with the same :class:`~fints.client.FinTS3Client` object. -The :func:`~fints.client.FinTS3Client.get_data` parameter `include_private` (defaults to `False`) enables +The :func:`~fints.client.FinTS3Client.deconstruct` parameter `include_private` (defaults to `False`) enables including the User Parameter Data in the datablob. Set this to `True` if you can sufficiently ensure the privacy of the returned datablob (mostly: user name and account numbers). @@ -33,7 +33,7 @@ If your system manages multiple users/identity contexts, you SHOULD keep distinc user or context. You SHOULD NOT call any other methods on the :class:`~fints.client.FinTS3Client` object -after calling :func:`~fints.client.FinTS3Client.get_data`. +after calling :func:`~fints.client.FinTS3Client.deconstruct`. Keeping the dialog open @@ -52,14 +52,14 @@ This can, and should be, complemented with the client state facility as follows: .. code-block:: python datablob = ... # get from backend storage, or set to None - client = FinTS3PinTanClient(..., set_data=datablob) + client = FinTS3PinTanClient(..., from_data=datablob) with client: accounts = client.get_sepa_accounts() balance = client.get_balance(accounts[0]) transactions = client.get_transactions(accounts[0]) - datablob = client.get_data() + datablob = client.deconstruct() # Store datablob to backend storage For transactions involving TANs it may be required by the bank to issue both steps for one transaction diff --git a/docs/tans.rst b/docs/tans.rst index 7b481d7..b1be0d1 100644 --- a/docs/tans.rst +++ b/docs/tans.rst @@ -135,7 +135,7 @@ You SHOULD use this facility together with the client and dialog state restorati response = client.sepa_transfer(...) dialog_data = client.pause_dialog() - client_data = client.get_data() + client_data = client.deconstruct() tan_data = response.get_data() .. code-block:: python @@ -149,7 +149,7 @@ You SHOULD use this facility together with the client and dialog state restorati :caption: Third step tan_request = NeedRetryResponse.from_data(tan_data) - client = FinTS3PinTanClient(..., set_data=client_data) + client = FinTS3PinTanClient(..., from_data=client_data) with client.resume_dialog(dialog_data): response = client.send_tan(tan_request, tan) diff --git a/fints/client.py b/fints/client.py index 997c3e0..6fc86ac 100644 --- a/fints/client.py +++ b/fints/client.py @@ -150,7 +150,7 @@ class TransactionResponse: class FinTS3Client: - def __init__(self, bank_identifier, user_id, customer_id=None, set_data: bytes=None): + def __init__(self, bank_identifier, user_id, customer_id=None, from_data: bytes=None): self.accounts = [] if isinstance(bank_identifier, BankIdentifier): self.bank_identifier = bank_identifier @@ -172,8 +172,8 @@ class FinTS3Client: self.response_callbacks = [] self._standing_dialog = None - if set_data: - self.set_data(bytes(set_data)) + if from_data: + self.set_data(bytes(from_data)) def _new_dialog(self, lazy_init=False): raise NotImplemented() @@ -268,7 +268,7 @@ class FinTS3Client: self.upa = SegmentSequence(data['upa_bin']).segments[0] self.upd_version = data['upd_version'] - def _get_data_v1(self, including_private=False): + def _deconstruct_v1(self, including_private=False): data = { "system_id": self.system_id, "bpd_bin": self.bpd.render_bytes(), @@ -285,8 +285,9 @@ class FinTS3Client: return data - def get_data(self, including_private: bool=False) -> bytes: - """Return state of this FinTSClient instance as an opaque datablob. + def deconstruct(self, including_private: bool=False) -> bytes: + """Return state of this FinTSClient instance as an opaque datablob. You should not + use this object after calling this method. Information about the connection is implicitly retrieved from the bank and cached in the FinTSClient. This includes: system identifier, bank parameter @@ -301,11 +302,11 @@ class FinTS3Client: Note: No connection information is stored in the datablob, neither is the PIN. """ - data = self._get_data_v1(including_private=including_private) + data = self._deconstruct_v1(including_private=including_private) return compress_datablob(DATA_BLOB_MAGIC, 1, data) def set_data(self, blob: bytes): - """Restore a datablob created with get_data(). + """Restore a datablob created with deconstruct(). You should only call this method once, and only immediately after constructing the object and before calling any other method or functionality (e.g. __enter__()). @@ -825,7 +826,7 @@ class FinTS3Client: Commands MUST NOT be issued in the dialog after calling this method. - MUST be used in conjunction with get_data()/set_data(). + MUST be used in conjunction with deconstruct()/set_data(). Caller SHOULD ensure that the dialog is resumed (and properly ended) within a reasonable amount of time. @@ -833,7 +834,7 @@ class FinTS3Client: :: - client = FinTS3PinTanClient(..., set_data=None) + client = FinTS3PinTanClient(..., from_data=None) with client: challenge = client.sepa_transfer(...) @@ -842,13 +843,13 @@ class FinTS3Client: # dialog is now frozen, no new commands may be issued # exiting the context does not end the dialog - client_data = client.get_data() + client_data = client.deconstruct() # Store dialog_data and client_data out-of-band somewhere # ... Some time passes ... # Later, possibly in a different process, restore the state - client = FinTS3PinTanClient(..., set_data=client_data) + client = FinTS3PinTanClient(..., from_data=client_data) with client.resume_dialog(dialog_data): client.send_tan(...) @@ -1017,8 +1018,8 @@ class FinTS3PinTanClient(FinTS3Client): self.selected_security_function = data.get('selected_security_function', self.selected_security_function) self.allowed_security_functions = data.get('allowed_security_functions', self.allowed_security_functions) - def _get_data_v1(self, including_private=False): - data = super()._get_data_v1(including_private=including_private) + def _deconstruct_v1(self, including_private=False): + data = super()._deconstruct_v1(including_private=including_private) data.update({ "selected_security_function": self.selected_security_function, "selected_tan_medium": self.selected_tan_medium, diff --git a/tests/test_client.py b/tests/test_client.py index 837986a..61a3421 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -57,14 +57,14 @@ def test_resume(fints_client, fints_server): d_data = fints_client.pause_dialog() - c_data = fints_client.get_data(including_private=True) + c_data = fints_client.deconstruct(including_private=True) FinTS3PinTanClient( '12345678', 'test1', '1234', fints_server, - set_data=c_data + from_data=c_data ) assert system_id == fints_client.system_id -- 2.39.5