From 3c974a883559d32f22d93b2f14c33133fde758b1 Mon Sep 17 00:00:00 2001
From: Martin Domke <mail@martindomke.net>
Date: Fri, 10 May 2024 15:44:10 +0200
Subject: [PATCH] Add changelog and examples for IBAN.random()

---
 CHANGELOG.rst            | 25 +++++++++++++++++++++++
 README.rst               |  1 +
 docs/source/examples.rst | 43 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index fc5b6bf..c5379ec 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -5,6 +5,30 @@ Changelog
 
 Versions follow `CalVer <http://www.calver.org/>`_ with the scheme ``YY.0M.Micro``.
 
+`2024.05.3`_ - 2024/05/10
+-------------------------
+Added
+~~~~~
+* There is a new classmethod ``IBAN.random()`` that allows you to create random, but valid IBANs.
+
+  .. code-block:: pycon
+
+    >>> IBAN.random()
+    <IBAN=LT435012771675726758>
+
+  You can narrow down the generated values by providing the corresponding parameters to this
+  function. E.g. to get only Spanish IBANs you can do
+
+  .. code-block:: pycon
+
+    >>> IBAN.random(country_code="ES")
+    <IBAN=ES8801253179194914182449>
+
+Changed
+~~~~~~~
+* Some missing bank associations have been added to the Portoguese bank registry by
+  `@tiagoafseixas <https://github.com/tiagoafseixas>`_
+
 `2024.05.2`_ - 2024/05/09
 -------------------------
 Fixed
@@ -599,6 +623,7 @@ Added
 * Added :attr:`.BIC.country` and :attr:`.IBAN.country`.
 
 
+.. _2024.05.3: https://github.com/mdomke/schwifty/compare/2024.05.2...2024.05.3
 .. _2024.05.2: https://github.com/mdomke/schwifty/compare/2024.05.1...2024.05.2
 .. _2024.05.1: https://github.com/mdomke/schwifty/compare/2024.05.0...2024.05.1
 .. _2024.05.0: https://github.com/mdomke/schwifty/compare/2024.04.0...2024.05.0
diff --git a/README.rst b/README.rst
index a05853f..0d19eec 100644
--- a/README.rst
+++ b/README.rst
@@ -28,6 +28,7 @@ Features
 * `validate`_ format and country codes from BICs
 * `generate`_ BICs from country and bank-code
 * `generate`_ IBANs from country-code, bank-code and account-number.
+* `generate`_ random valid IBANs
 * get the BIC associated to an IBAN's bank-code
 * access all relevant components as attributes
 
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 369af28..1041f8b 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -259,6 +259,49 @@ In case there are multiple BICs that can be related to a domestic bank code you
    <BIC=BNPAFRPPPEE>, <BIC=BNPAFRPPPXV>, <BIC=BNPAFRPPIFO>]
 
 
+Random IBANs
+~~~~~~~~~~~~
+
+For testing and other usecases it might be useful to generate random IBANs. Therefore you can simply
+call
+
+.. code-block:: pycon
+
+  >>> IBAN.random()
+  <IBAN=IT53D0838265738IXCFNXEVWPNL>
+
+and you will get a random but valid IBAN. You can also predefine some parameters of the random
+result to narrow down the possible values, e.g.
+
+.. code-block:: pycon
+
+  >>> IBAN.random(country_code="GB")
+  <IBAN=GB67COBA74887171221908>
+
+will give you a British IBAN. Similarly,
+
+.. code-block:: pycon
+
+  >>> IBAN.random(country_code="GB", bank_code="LOYD")
+  <IBAN=GB53LOYD00952296262556>
+
+will only give you IBANs from the Lloyds Bank.
+
+Notice that for countries that have a bank registry, the bank code will always be taken from there,
+so that the IBAN corresponds to a valid bank. E.g.:
+
+.. code-block:: pycon
+
+  >>> IBAN.random(country_code="DE").bank
+  {'bank_code': '42870077',
+   'name': 'Deutsche Bank',
+   'short_name': 'Deutsche Bank',
+   'bic': 'DEUTDE3B428',
+   'primary': True,
+   'country_code': 'DE',
+   'checksum_algo': '63'}
+
+
 Pydantic integration
 ---------------------