Schwifty

https://schwifty.readthedocs.io/en/latest/
Admin
Schwifty is a Python library for validating, generating, and working with IBANs and BICs for...
Tokens:28,345
Snippets:343
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install schwifty

Source: https://schwifty.readthedocs.io/en/latest/index.html

Install the schwifty Python library using pip. Requires Python 3.6+.

```bash
$ pip install schwifty

```

--------------------------------

### IBAN Validate BBAN Checksum Example (Constructor)

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Shows how to opt-in to BBAN checksum validation using the `IBAN` constructor parameter.

```python
>>> IBAN('DE20 2909 0900 8840 0170 00', validate_bban=True)
... 
InvalidBBANChecksum: Invalid BBAN checksum
```

--------------------------------

### IBAN Validate BBAN Checksum Example (Method)

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Shows how to opt-in to BBAN checksum validation using the `validate` method.

```python
>>> iban = IBAN('DE20 2909 0900 8840 0170 00')
>>> iban.validate(validate_bban=True)
... 
InvalidBBANChecksum: Invalid BBAN checksum
```

--------------------------------

### Get Formatted BIC

Source: https://schwifty.readthedocs.io/en/latest/api.html

Get the BIC string formatted with spaces separating the bank, country, and location codes.

```python
>>> BIC("MARKDEF1100").formatted
'MARK DE F1 100'
```

--------------------------------

### BIC Invalid Structure Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Demonstrates a BIC validation error for an invalid structure.

```python
>>> BIC('PBNKD1FFXXXX')
... 
InvalidStructure: Invalid structure PBN1DXFFXXXX
```

--------------------------------

### IBAN Invalid Country Code Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Demonstrates an IBAN validation error for an unknown country code.

```python
>>> IBAN('DX89 3704 0044 0532 0130 00')
... 
InvalidCountryCode: Unknown country-code DX
```

--------------------------------

### BIC Strict SWIFT Compliance Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Shows how to enforce strict SWIFT compliance for BIC validation, disallowing numbers in the business prefix.

```python
>>> BIC("1234DEWWXXX", enforce_swift_compliance=True)
... 
InvalidStructure: Invalid structure 1234DEWWXXX
```

--------------------------------

### IBAN Invalid Checksum Digits Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Demonstrates an IBAN validation error due to incorrect checksum digits.

```python
>>> IBAN('DE99 3704 0044 0532 0130 00')
... 
InvalidChecksumDigits: Invalid checksum digits
```

--------------------------------

### BIC Invalid Length Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Demonstrates a BIC validation error for an incorrect length.

```python
>>> BIC('PBNKDXFFXXXX')
... 
InvalidLength: Invalid length 12
```

--------------------------------

### Get Bank Information for Random IBAN

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Generates a random IBAN for a specified country and retrieves its associated bank information from the registry.

```python
>>> 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'}
```

--------------------------------

### Get IBAN Account Type

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the account type specifier. This is only available for IBANs from Seychelles, Brazil, and Bulgaria.

```python
@property
def account_type(self) -> str:
    """str: Account type specifier.

    This value is only available for Seychelles, Brazil and Bulgaria.
    """
    return self.bban.account_type
```

--------------------------------

### Get IBAN Currency Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the currency code of the account. This is only available for IBANs from Mauretania, Seychelles, and Guatemala.

```python
@property
def currency_code(self) -> str:
    """str: The account's currency code.

    This value is only available for Mauretania, Seychelles and Guatemala.
    """
    return self.bban.currency_code
```

--------------------------------

### Get Domestic Bank Codes from BIC

Source: https://schwifty.readthedocs.io/en/latest/_sources/examples.rst.txt

Lists the country-specific bank codes associated with a BIC.

```pycon
>>> bic.domestic_bank_codes
['10010010',
 '20010020',
 ...
 '86010090']
```

--------------------------------

### BIC Invalid Country Code Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Demonstrates a BIC validation error for an invalid country code.

```python
>>> BIC('PBNKDXFFXXX')
... 
InvalidCountryCode: Invalid country code DX
```

--------------------------------

### Get IBAN Account Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the domestic account code, which is part of the BBAN.

```python
@property
def account_code(self) -> str:
    """str: The domestic account-code"""
    return self.bban.account_code
```

--------------------------------

### Get IBAN Bank Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the country-specific bank code, which is a component of the BBAN.

```python
@property
def bank_code(self) -> str:
    """str: The country specific bank-code."""
    return self.bban.bank_code
```

--------------------------------

### IBAN is_valid Property Example

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Illustrates using the `is_valid` property for a non-exceptional IBAN validation check. Note that this does not validate national checksum digits.

```python
if IBAN(value, allow_invalid=True).is_valid:
  # do something with value
```

--------------------------------

### Get IBAN Bank Information

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns a dictionary containing information about the bank associated with the IBAN's bank code, as part of the BBAN. Returns None if no information is available.

```python
@property
def bank(self) -> dict | None:
    """dict or None: The information of the bank related to the bank code as part of the BBAN"""
    return self.bban.bank
```

--------------------------------

### Get IBAN Branch Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the branch code of the bank, if available as part of the BBAN.

```python
@property
def branch_code(self) -> str:
    """str: The branch-code of the bank if available."""
    return self.bban.branch_code
```

--------------------------------

### Get IBAN Account ID

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the holder-specific account identification. Currently, this is only available for IBANs from Brazil.

```python
@property
def account_id(self) -> str:
    """str: Holder specific account identification.

    This is currently only available for Brazil.
    """
    return self.bban.account_id
```

--------------------------------

### Get IBAN Country Specification

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that retrieves the country-specific IBAN specification from the registry. Raises an InvalidCountryCode exception if the country code is unknown.

```python
@property
def spec(self) -> dict[str, Any]:
    """dict: The country specific IBAN specification."""
    try:
        spec = registry.get("iban")
        assert isinstance(spec, dict)
        return spec[self.country_code]
    except KeyError as e:
        raise exceptions.InvalidCountryCode(
            f"Unknown country-code '{self.country_code}'"
        ) from e
```

--------------------------------

### Get BIC candidates from bank code

Source: https://schwifty.readthedocs.io/en/latest/_sources/examples.rst.txt

Retrieve a list of all known BIC candidates associated with a given domestic bank code and country. This is useful when multiple BICs might correspond to a single bank code.

```pycon
>>> BIC.candidates_from_bank_code('FR', '30004') # doctest: +NORMALIZE_WHITESPACE
[<BIC=BNPAFRPPIFN>, <BIC=BNPAFRPPPAA>, <BIC=BNPAFRPPMED>, <BIC=BNPAFRPPCRN>,
 <BIC=BNPAFRPP>, <BIC=BNPAFRPPPAE>, <BIC=BNPAFRPPPBQ>, <BIC=BNPAFRPPNFE>,
 <BIC=BNPAFRPPPGN>, <BIC=BNPAFRPPXXX>, <BIC=BNPAFRPPBOR>, <BIC=BNPAFRPPCRM>,
 <BIC=BNPAFRPPPVD>, <BIC=BNPAFRPPPTX>, <BIC=BNPAFRPPPAC>, <BIC=BNPAFRPPPLZ>,
 <BIC=BNPAFRPP039>, <BIC=BNPAFRPPENG>, <BIC=BNPAFRPPNEU>, <BIC=BNPAFRPPORE>,
 <BIC=BNPAFRPPPEE>, <BIC=BNPAFRPPPXV>, <BIC=BNPAFRPPIFO>]
```

--------------------------------

### Get IBAN Bank Short Name

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that retrieves a shortened name of the bank associated with the IBAN's bank code. Returns None if the short name is not available.

```python
@property
def bank_short_name(self) -> str | None:
    """str or None: The name of the bank associated with the IBAN bank code.

    Examples:
        >>> IBAN("DE89370400440532013000").bank_short_name
        'Commerzbank Köln'


```

--------------------------------

### Get IBAN Country Information

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that retrieves the country object associated with the IBAN's country code. Returns None if the country code is not found.

```python
@property
def country(self) -> Data | None:
    """Country: The country this IBAN is registered in."""
    return countries.get(alpha_2=self.country_code)
```

--------------------------------

### Get IBAN Bank Name

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that retrieves the full name of the bank associated with the IBAN's bank code. Returns None if the bank name is not available.

```python
@property
def bank_name(self) -> str | None:
    """str or None: The name of the bank associated with the IBAN bank code.

    Examples:
        >>> IBAN("DE89370400440532013000").bank_name
        'Commerzbank'

    .. versionadded:: 2022.04.2
    """
    return self.bban.bank_name
```

--------------------------------

### Instantiate BBAN from Components

Source: https://schwifty.readthedocs.io/en/latest/api.html

Demonstrates how to create a BBAN object by providing the country code and specific components like the account code and bank code.

```python
>>> BBAN.from_components("DE", account_code="0532013000", bank_code="37040044")
<BBAN=370400440532013000>
```

--------------------------------

### Get Bank Names of a BIC

Source: https://schwifty.readthedocs.io/en/latest/api.html

Retrieve a list of bank names associated with a BIC. This is the recommended way to get bank names since version 2020.01.0.

```python
>>> BIC("MARKDEF1100").bank_names
['Bundesbank']
```

--------------------------------

### Get Domestic Bank Codes of a BIC

Source: https://schwifty.readthedocs.io/en/latest/api.html

Retrieve a list of country-specific bank codes associated with a BIC. This is the recommended way to get domestic bank codes since version 2020.01.0.

```python
>>> BIC("MARKDEF1100").domestic_bank_codes
['10000000']
```

--------------------------------

### Create BIC Object

Source: https://schwifty.readthedocs.io/en/latest/_sources/examples.rst.txt

Demonstrates how to create a BIC object from its string representation.

```pycon
>>> from schwifty import BIC
>>> bic = BIC('PBNKDEFFXXX')
>>> bic.bank_code
'PBNK'
>>> bic.branch_code
'XXX'
>>> bic.country_code
'DE'
>>> bic.location_code
'FF'
```

--------------------------------

### Get Bank Short Names of a BIC

Source: https://schwifty.readthedocs.io/en/latest/api.html

Retrieve a list of short bank names associated with a BIC. This is the recommended way to get bank short names since version 2020.01.0.

```python
>>> BIC("MARKDEF1100").bank_short_names
['BBk Berlin']
```

--------------------------------

### Generate IBAN with Country-Specific Components

Source: https://schwifty.readthedocs.io/en/latest/changelog.html

Demonstrates how to generate an IBAN by providing country-specific components like bank code, account type, account code, and account holder ID.

```python
>>> IBAN.generate("IS", bank_code="0101", account_type="26", account_code="85002", account_holder_id="5402696029")
<IBAN=IS910101260850025402696029>
```

--------------------------------

### Get BIC Location Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Extracts the location code from a BIC.

```python
from schwifty import BIC

print(BIC("MARKDEF1100").location_code)
# Expected output: '1100'
```

--------------------------------

### Create and Access IBAN Components

Source: https://schwifty.readthedocs.io/en/latest/api.html

Instantiate an IBAN object with a given code and access its various components as properties. The IBAN is validated upon creation.

```python
>>> iban = IBAN('DE89 3704 0044 0532 0130 00')
>>> iban.account_code
'0532013000'
>>> iban.bank_code
'37040044'
>>> iban.country_code
'DE'
>>> iban.checksum_digits
'89'
>>> iban.bban
<BBAN=370400440532013000>
```

--------------------------------

### Get BIC Bank Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Extracts the bank code part from a BIC.

```python
from schwifty import BIC

print(BIC("MARKDEF1100").bank_code)
# Expected output: 'MARK'
```

--------------------------------

### Get Bank Name from BBAN

Source: https://schwifty.readthedocs.io/en/latest/api.html

Retrieves the name of the bank associated with a BBAN object.

```python
>>> BBAN("DE", "370400440532013000").bank_name
'Commerzbank'
```

--------------------------------

### Instantiate and Access IBAN Components

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Create an IBAN object from a string and access its components like account code, bank code, country code, checksum digits, and the BBAN object. Validation is performed on instantiation unless `allow_invalid` is True.

```python
from schwifty import IBAN

try:
    iban = IBAN('DE89 3704 0044 0532 0130 00')
    print(f'Account Code: {iban.account_code}')
    print(f'Bank Code: {iban.bank_code}')
    print(f'Country Code: {iban.country_code}')
    print(f'Checksum Digits: {iban.checksum_digits}')
    print(f'BBAN: {iban.bban}')
except exceptions.InvalidStructure as e:
    print(f'Invalid structure: {e}')
except exceptions.InvalidChecksumDigits as e:
    print(f'Invalid checksum: {e}')
except exceptions.InvalidLength as e:
    print(f'Invalid length: {e}')
```

--------------------------------

### BIC Class Initialization

Source: https://schwifty.readthedocs.io/en/latest/api.html

Instantiate a BIC object with a given code. Validation is performed by default, but can be bypassed or made stricter using parameters.

```APIDOC
## BIC Class Initialization

### Description
Instantiate a BIC object with a given code. Validation is performed by default, but can be bypassed or made stricter using parameters.

### Parameters

* **_value** (_str_) – The BIC value.
* **allow_invalid** (_bool_) – If set to `True` validation is skipped on instantiation.
* **enforce_swift_compliance** (_bool_) – If set to `True` the stricter SWIFT BIC policy is applied.

### Raises

* **InvalidLength** – If the BIC’s length is not 8 or 11 characters long.
* **InvalidStructure** – If the BIC contains unexpected characters.
* **InvalidCountryCode** – If the BIC’s country code is unknown.

### Examples
```python
>>> bic = BIC('GENODEM1GLS')
>>> bic.country_code
'DE'
>>> bic.location_code
'M1'
>>> bic.bank_code
'GENO'
```
```

--------------------------------

### Get BIC Branch Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Extracts the branch code part from a BIC, if available.

```python
from schwifty import BIC

print(BIC("MARKDEF1100").branch_code)
# Expected output: '1100'
```

--------------------------------

### Generate IBAN with Checksum

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Generates an IBAN from country code, bank code, and account number. The checksum digits are automatically calculated.

```python
>>> iban = IBAN.generate('DE', bank_code='10010010', account_code='12345')
<IBAN=DE40100100100000012345>
>>> iban.checksum_digits
'40'
```

--------------------------------

### Create IBAN object from string

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Instantiate an IBAN object from its string representation. This is the primary way to create IBAN objects.

```python
>>> from schwifty import IBAN
>>> iban = IBAN('DE89 3704 0044 0532 0130 00')
<IBAN=DE89370400440532013000>
```

--------------------------------

### PyInstaller Data Collection

Source: https://schwifty.readthedocs.io/en/latest/changelog.html

Use this command when packaging the library with PyInstaller to ensure data files are collected and metadata is copied.

```bash
$ pyinstaller <script> --collect-data schwifty --copy-metadata schwifty

```

--------------------------------

### Get BIC Country Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Extracts the ISO 3166 alpha2 country code from a BIC.

```python
from schwifty import BIC

print(BIC("MARKDEF1100").country_code)
# Expected output: 'DE'
```

--------------------------------

### IBAN Instantiation

Source: https://schwifty.readthedocs.io/en/latest/api.html

Creates an IBAN object from a string. Validation is performed by default, but can be skipped. Optionally, BBAN checksum validation can also be controlled.

```APIDOC
## IBAN Class

### Description
The IBAN object represents an International Bank Account Number. It is validated upon creation and provides access to its components as properties.

### Class Signature
`class schwifty.IBAN(_value: str, _**kwargs: Any)`

### Parameters
* **_value** (str) - The IBAN code.
* **allow_invalid** (bool) - If set to True, IBAN validation is skipped on instantiation.
* **validate_bban** (bool) - If set to True, also check the country-specific checksum of the BBAN.

### Raises
* **InvalidStructure** - If the IBAN contains invalid characters or the BBAN does not match the country-specific format.
* **InvalidChecksumDigits** - If the IBAN’s checksum is invalid.
* **InvalidBBANChecksum** - If the country-specific BBAN checksum is invalid and `validate_bban` was set to True.
* **InvalidLength** - If the length does not match the country-specific specification.

### Example
```python
>>> iban = IBAN('DE89 3704 0044 0532 0130 00')
>>> iban.account_code
'0532013000'
>>> iban.bank_code
'37040044'
>>> iban.country_code
'DE'
>>> iban.checksum_digits
'89'
>>> iban.bban
<BBAN=370400440532013000>
```
```

--------------------------------

### Get BIC Country

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Retrieves the country object associated with the BIC's country code.

```python
from schwifty import BIC

bic = BIC("MARKDEF1100")
print(bic.country.name)
# Expected output: 'Germany'
```

--------------------------------

### IBAN Instantiation and Properties

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Instantiate an IBAN object with an IBAN code. The object provides access to its components like country code, bank code, account code, and checksum digits. Validation is performed by default.

```APIDOC
## IBAN Instantiation

### Description
Creates a new IBAN object by supplying an IBAN code in text form. The IBAN is validated behind the scenes, and its components can be accessed as properties.

### Arguments
* `iban` (str): The IBAN code.
* `allow_invalid` (bool): If `True`, IBAN validation is skipped on instantiation. Defaults to `False`.
* `validate_bban` (bool): If `True`, also checks the country-specific checksum of the BBAN. Defaults to `False`.

### Raises
* `InvalidStructure`: If the IBAN contains invalid characters or the BBAN does not match the country-specific format.
* `InvalidChecksumDigits`: If the IBAN's checksum is invalid.
* `InvalidBBANChecksum`: If the country-specific BBAN checksum is invalid and `validate_bban` was set to `True`.
* `InvalidLength`: If the length does not match the country-specific specification.

### Properties
* `account_code` (str): The account number part of the IBAN.
* `bank_code` (str): The bank code part of the IBAN.
* `country_code` (str): The ISO 3166 alpha-2 country code.
* `checksum_digits` (str): The two checksum digits of the IBAN.
* `bban` (BBAN): The BBAN object containing country-specific account and bank information.

### Example
```python
from schwifty import IBAN

try:
    iban = IBAN('DE89 3704 0044 0532 0130 00')
    print(iban.account_code)
    print(iban.bank_code)
    print(iban.country_code)
    print(iban.checksum_digits)
    print(iban.bban)
except Exception as e:
    print(f"Error: {e}")
```
```

--------------------------------

### IBAN and BIC as string subclasses

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Demonstrates that IBAN and BIC objects inherit from `str`, allowing direct use of string methods like slicing and counting.

```python
>>> iban = IBAN('DE89 3704 0044 0532 0130 00')
>>> iban[2:4]
"89"
>>> iban.count("0")
8
>>> iban.startswith("DE")
True
```

--------------------------------

### IBAN Validation - Invalid BBAN Checksum (Opt-in)

Source: https://schwifty.readthedocs.io/en/latest/_sources/examples.rst.txt

Demonstrates the exception for an invalid BBAN checksum when validation is enabled.

```pycon
>>> iban = IBAN('DE20 2909 0900 8840 0170 00')
>>> iban.validate(validate_bban=True)
... 
InvalidBBANChecksum: Invalid BBAN checksum

>>> IBAN('DE20 2909 0900 8840 0170 00', validate_bban=True)
... 
InvalidBBANChecksum: Invalid BBAN checksum
```

--------------------------------

### Get Bank Short Name from BBAN

Source: https://schwifty.readthedocs.io/en/latest/api.html

Retrieves the short name of the bank associated with a BBAN object.

```python
>>> BBAN("DE", "370400440532013000").bank_short_name
'Commerzbank Köln'
```

--------------------------------

### Generate a random IBAN

Source: https://schwifty.readthedocs.io/en/latest/changelog.html

Use the `IBAN.random()` classmethod to create a random, valid IBAN. This method can be used without arguments for a globally random IBAN or with parameters to specify country-specific generation.

```python
>>> IBAN.random()
<IBAN=LT435012771675726758>
```

--------------------------------

### Country Specific Bank Code for BIC

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Property to get the country-specific bank code associated with the BIC.

```python
@property
def country_bank_code(self) -> str | None:
    """str or None: The country specific bank-code associated with the BIC.

    
```

--------------------------------

### BBAN Construction from Components

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bban.html

Constructs a BBAN object from its components, calculating and applying the national checksum if applicable. It assembles the BBAN string based on country-specific length and position specifications.

```python
if len(components[Component.ACCOUNT_CODE]) > account_code_length:
            raise exceptions.InvalidAccountCode(
                f"Account code exceeds maximum size {account_code_length}"
            )

        checksum = compute_national_checksum(country_code, components)
        if checksum:
            components[Component.NATIONAL_CHECKSUM_DIGITS] = checksum

        bban = "0" * spec["bban_length"]
        for key, value in components.items():
            range_ = ranges[key]
            if range_.is_empty:
                continue
            bban = bban[: range_.start] + value + bban[range_.end :]

        return cls(country_code, bban)
```

--------------------------------

### Create BIC from bank code and country code (alternative)

Source: https://schwifty.readthedocs.io/en/latest/api.html

Create a BIC object using the from_bank_code classmethod. This method is suitable for generating a single BIC instance from country and bank codes, inferring the full BIC structure.

```python
>>> bic = BIC.from_bank_code("DE", "20070000")
>>> bic.country_code
'DE'
>>> bic.bank_code
'DEUT'
>>> bic.location_code
'HH'
```

```python
>>> BIC.from_bank_code("DE", "01010101")
Traceback (most recent call last):
... 
InvalidBankCode: Unknown bank code '01010101' for country 'DE'
```

--------------------------------

### Create BIC from text

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Instantiate a BIC object by providing the BIC code as a string. The code is validated upon creation unless allow_invalid is set to True.

```python
from schwifty import BIC

bic = BIC('GENODEM1GLS')
print(bic.country_code)
print(bic.location_code)
print(bic.bank_code)
```

--------------------------------

### Exceptions Module

Source: https://schwifty.readthedocs.io/en/latest/_sources/api.rst.txt

Contains custom exception classes for handling errors within the schwifty library.

```APIDOC
## Exceptions Module

### Description
This module contains custom exception classes used by the schwifty library for error handling.

### Module
`schwifty.exceptions`

### Members
(Details of members are not specified in the source, but the module is documented.)
```

--------------------------------

### Formatted BIC String

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Returns the BIC formatted with spaces separating the bank, country, location, and branch codes.

```python
@property
def formatted(self) -> str:
    """str: The BIC separated in the blocks bank-, country- and location-code.

    Examples:
        >>> BIC("MARKDEF1100").formatted
        'MARK DE F1 100'
    """
    formatted = " ".join([self.bank_code, self.country_code, self.location_code])
    if self.branch_code:
        formatted += " " + self.branch_code
    return formatted
```

--------------------------------

### Pydantic integration for IBAN validation

Source: https://schwifty.readthedocs.io/en/latest/_sources/examples.rst.txt

Demonstrates how to use `IBAN` objects directly with Pydantic models for data validation. By default, invalid values will raise a `ValidationError`.

```python
from pydantic import BaseModel
from schwifty import IBAN


class Model(BaseModel):
  iban: IBAN

model = Model(iban="DE89370400440532013000")  # OK
model = Model(iban="DX89370400440532013000")  # Raises ValidationError due to invalid country code
```

--------------------------------

### Get Bank Name from IBAN

Source: https://schwifty.readthedocs.io/en/latest/api.html

Retrieve the full name of the bank associated with an IBAN. This requires the IBAN object to be constructed.

```python
IBAN("DE89370400440532013000").bank_name
```

--------------------------------

### Get IBAN Country Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that extracts and returns the ISO 3166 alpha-2 country code from the beginning of the IBAN.

```python
@property
def country_code(self) -> str:
    """str: ISO 3166 alpha-2 country code."""
    return self._get_slice(start=0, end=2)
```

--------------------------------

### Generate random IBAN with bank details

Source: https://schwifty.readthedocs.io/en/latest/_sources/examples.rst.txt

When generating a random IBAN for countries with a bank registry, the bank code will be taken from the registry, ensuring the IBAN corresponds to a valid bank. If `use_registry=False` is set, the bank field will be None.

```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'}
```

```pycon
>>> IBAN.random(country_code="DE", use_registry=False).bank
None
```

--------------------------------

### Generate Random IBAN for Specific Bank

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Generates a random IBAN for a specified country and bank code.

```python
>>> IBAN.random(country_code="GB", bank_code="LOYD")
<IBAN=GB53LOYD00952296262556>
```

--------------------------------

### Get IBAN Checksum Digits

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that extracts and returns the two-digit checksum of the Basic Bank Account Number (BBAN) from the IBAN.

```python
@property
def checksum_digits(self) -> str:
    """str: Two digit checksum of the BBAN."""
    return self._get_slice(start=2, end=4)
```

--------------------------------

### Create IBAN from BBAN components

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Constructs an IBAN object from country code, bank code, account code, and optional branch code or other country-specific fields. Supports generating country-specific checksums for Belgian banks.

```python
cls.from_bban(
 country_code,
 BBAN.from_components(
 country_code,
 bank_code=bank_code,
 branch_code=branch_code,
 account_code=account_code,
 **kwargs,
 ),
 )
```

--------------------------------

### Instantiate BBAN from components

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bban.html

BBAN objects are typically created implicitly by the IBAN class. However, they can also be instantiated directly using the `from_components` class method, providing the country code and relevant national components.

```python
from schwifty import BBAN

BBAN.from_components("DE", account_code="0532013000", bank_code="37040044")
```

--------------------------------

### Get BIC Type

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Determines the type of BIC based on its location code. Supported types are 'testing', 'passive', 'reverse billing', and 'default'.

```python
from schwifty import BIC

print(BIC("MARKDEF1100").type)
# Expected output: 'passive'
```

--------------------------------

### Generate IBAN from Components

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Generate a valid IBAN by providing the country code, bank code, and account code. The function handles padding for bank and account codes if they are shorter than required. An optional branch code can also be provided.

```python
from schwifty import IBAN

bank_code = '37040044'
account_code = '532013000'

ibans = {
    'DE': IBAN.generate('DE', bank_code, account_code),
    'GB': IBAN.generate('GB', '112233', '4000001234'),
    'FR': IBAN.generate('FR', '30056', '000001234567890', branch_code='00001')
}

for country, iban in ibans.items():
    print(f'{country}: {iban.formatted}')
```

--------------------------------

### Generate Random IBAN

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Generates a random but valid IBAN. Useful for testing purposes.

```python
>>> IBAN.random()
<IBAN=IT53D0838265738IXCFNXEVWPNL>
```

--------------------------------

### Create BIC from code string

Source: https://schwifty.readthedocs.io/en/latest/api.html

Instantiate a BIC object by providing a BIC code as a string. The code is validated upon creation unless allow_invalid is True. Strict SWIFT compliance can be enforced with enforce_swift_compliance=True.

```python
>>> bic = BIC('GENODEM1GLS')
>>> bic.country_code
'DE'
>>> bic.location_code
'M1'
>>> bic.bank_code
'GENO'
```

--------------------------------

### Get Numeric Representation of IBAN

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns an integer representing the IBAN, formed by concatenating the BBAN and the first four characters of the IBAN.

```python
@property
def numeric(self) -> int:
    """int: A numeric represenation of the IBAN."""
    return numerify(self.bban + self[:4])
```

--------------------------------

### Generate IBAN with National Checksum

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Generates an IBAN for countries with a national checksum. The national checksum is automatically calculated.

```python
>>> iban = IBAN.generate("ES", "2100", "0200051332", "0418")
<IBAN=ES9121000418450200051332>
>>> iban.bban.national_checksum_digits
'45'
```

--------------------------------

### Get IBAN Account Holder ID

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the account holder's national identification number. This is currently only available for IBANs from Iceland.

```python
@property
def account_holder_id(self) -> str:
    """str: Account holder's national identification.

    This value is only available for Iceland.
    """
    return self.bban.account_holder_id
```

--------------------------------

### Get IBAN National Checksum Digits

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the national checksum digits specific to the country's banking system. This is part of the BBAN.

```python
@property
def national_checksum_digits(self) -> str:
    """str: National checksum digits.

    .. versionadded:: 2024.01.1
    """
    return self.bban.national_checksum_digits
```

--------------------------------

### BBAN.from_components

Source: https://schwifty.readthedocs.io/en/latest/api.html

Generates a BBAN from its national components. This class method allows for the creation of a BBAN object by providing specific components relevant to the country's BBAN structure.

```APIDOC
## BBAN.from_components

### Description
Generate a BBAN from its national components. The currently supported `values` are `bank_code`, `branch_code`, `account_code`, `account_id`, `account_type`, `account_holder_id`, `currency_code`, `national_checksum_digits`.

### Parameters
* **country_code** (_str_) – The ISO 3166 alpha-2 country code.
* **values** – The country specific BBAN components.

### Raises
* **InvalidAccountCode** – If the account code does not meet the national requirements.
```

--------------------------------

### Create BIC from bank code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Use the from_bank_code classmethod to create a BIC object from a country code and a domestic bank code. This method generates potential BIC codes based on the provided information.

```python
from schwifty import BIC

bic = BIC.from_bank_code('DE', '43060967')
print(bic.formatted)
```

--------------------------------

### Create BIC from Bank Code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

Creates a BIC object using a country code and a domestic bank code. It handles cases with multiple potential BIC matches by prioritizing generic codes.

```python
from schwifty import BIC

bic = BIC.from_bank_code("DE", "20070000")
print(bic.country_code)
print(bic.bank_code)
print(bic.location_code)
```

```python
from schwifty import BIC

try:
    BIC.from_bank_code("DE", "01010101")
except Exception as e:
    print(e)
```

--------------------------------

### Get BIC from IBAN

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Retrieve the associated BIC (Bank Identifier Code) for an IBAN if available for the country. The BIC object has a similar interface to the IBAN object.

```python
>>> iban.bic
<BIC=COBADEFFXXX>
```

--------------------------------

### Generate BIC candidates from bank code

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bic.html

The candidates_from_bank_code classmethod generates a list of potential BIC objects from a given country code and domestic bank code. This is useful when the exact BIC is unknown but the bank and country are specified.

```python
from schwifty import BIC

bic_codes = BIC.candidates_from_bank_code("FR", "30004")
print(bic_codes) # doctest: +ELLIPSIS

bic_codes = BIC.candidates_from_bank_code("DE", "20070024") # doctest: +ELLIPSIS
print(bic_codes)
```

--------------------------------

### GenerateRandomOverflowError

Source: https://schwifty.readthedocs.io/en/latest/api.html

Indicates that during random entity generation, no valid value could be found. This could for example be the case if the national checksum digit does not compute for a randomly chosen account code.

```APIDOC
## Exception GenerateRandomOverflowError

### Description
Indicates that during random entity generation, no valid value could be found. This could for example be the case if the national checksum digit does not compute for a randomly chosen account code.

### Source
schwifty.exceptions.GenerateRandomOverflowError
```

--------------------------------

### Generate IBAN

Source: https://schwifty.readthedocs.io/en/latest/api.html

Generates an IBAN from its components: country code, bank code, and account code. Optional branch code and other country-specific fields can be provided.

```APIDOC
### Class Method: `generate`

#### Description
Generate an IBAN from its components. If the bank-code and/or account-number have fewer digits than required by their country-specific representation, the respective component is padded with zeros.

#### Signature
`classmethod generate(_country_code: str, _bank_code: str, _account_code: str, _branch_code: str = '', _**kwargs: Any) -> IBAN`

#### Parameters
* **country_code** (str) - The ISO 3166 alpha-2 country code.
* **bank_code** (str) - The country-specific bank-code.
* **account_code** (str) - The customer-specific account-code.
* **branch_code** (str, optional) - The branch code (or sort code). Defaults to ''.
* **kwargs** (Any) - Additional country-specific fields.

#### Raises
* **InvalidAccountCode** - If the account code does not meet the national requirements.

#### Example
```python
>>> bank_code = '37040044'
>>> account_code = '532013000'
>>> iban = IBAN.generate('DE', bank_code, account_code)
>>> iban.formatted
'DE89 3704 0044 0532 0130 00'
```

Changed in version 2020.08.3: Added the `branch_code` parameter.
Changed in version 2021.05.2: Added support for generating the country-specific checksum of the BBAN for Belgian banks.
```

--------------------------------

### Build Bank Code Index

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/bban.html

Builds an index for bank codes, keyed by country code, with accumulation enabled. This is a utility function for organizing bank data.

```python
registry.build_index("bank", "country", key="country_code", accumulate=True)
```

--------------------------------

### Get Associated BIC for IBAN

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Property that returns the Business Identifier Code (BIC) associated with the IBAN's bank code. Returns None if the bank code is not found in schwifty's registry.

```python
@property
def bic(self) -> BIC | None:
    """BIC or None: The BIC associated to the IBAN's bank-code.

    If the bank code is not available in schwifty's registry ``None`` is returned.

    .. versionchanged:: 2020.08.1
        Returns ``None`` if no appropriate :class:`BIC` can be constructed.
    """
    return self.bban.bic
```

--------------------------------

### Generate a random IBAN

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Generates a random IBAN. By default, it selects a random bank from the registry. Supports specifying a country code and providing BBAN components to narrow down generation. Can ignore the registry by setting `use_registry` to `False`.

```python
cls.random(
 country_code: str = "",
 random: Random | None = None,
 use_registry: bool = True,
 **values: str,
 ) -> IBAN:
```

--------------------------------

### Create BIC object from string

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Instantiate a BIC object from its string representation. This object provides access to various components of the BIC.

```python
>>> from schwifty import BIC
>>> bic = BIC('PBNKDEFFXXX')
>>> bic.bank_code
'PBNK'
>>> bic.branch_code
'XXX'
>>> bic.country_code
'DE'
>>> bic.location_code
'FF'
>>> bic.domestic_bank_codes
['10010010',
 '20010020',
 ...
 '86010090']
```

--------------------------------

### Generate IBAN from Components

Source: https://schwifty.readthedocs.io/en/latest/api.html

Generate an IBAN object by providing country code, bank code, and account code. The function automatically calculates checksum digits and handles zero-padding for components with fewer digits than required.

```python
>>> bank_code = '37040044'
>>> account_code = '532013000'
>>> iban = IBAN.generate('DE', bank_code, account_code)
>>> iban.formatted
'DE89 3704 0044 0532 0130 00'
```

--------------------------------

### Pydantic Core Schema for IBAN

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Defines how the IBAN class integrates with Pydantic's core schema system, supporting both lax and strict validation modes.

```python
from pydantic_core import core_schema

return core_schema.lax_or_strict_schema(
    cls._get_pydantic_schema(allow_invalid=True),
    cls._get_pydantic_schema(allow_invalid=False),
    strict=True,
)
```

--------------------------------

### Create IBAN from BBAN

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Construct an IBAN object using a country code and a Basic Bank Account Number (BBAN). This method automatically calculates the necessary IBAN checksum digits. The `validate_bban` parameter can be used to also check the country-specific BBAN checksum.

```python
from schwifty import IBAN

# Example with a string BBAN
iban_from_string_bban = IBAN.from_bban('DE', '370400440532013000')
print(iban_from_string_bban.formatted)

# Example with a BBAN object (assuming BBAN object is created elsewhere)
# from schwifty.bban import BBAN
# bban_obj = BBAN('DE', '370400440532013000')
# iban_from_bban_obj = IBAN.from_bban('DE', bban_obj)
# print(iban_from_bban_obj.formatted)
```

--------------------------------

### Generate Random IBAN for Specific Country

Source: https://schwifty.readthedocs.io/en/latest/examples.html

Generates a random IBAN for a specified country code.

```python
>>> IBAN.random(country_code="GB")
<IBAN=GB67COBA74887171221908>
```

--------------------------------

### IBAN Properties

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

This section details the various properties available on an IBAN object, providing access to its components and related information.

```APIDOC
## IBAN Properties

This section details the various properties available on an IBAN object, providing access to its components and related information.

### Properties

- **is_valid** (bool): Indicate if this is a valid IBAN. Note: You have to use the `allow_invalid` parameter when constructing the :class:`IBAN`-object to circumvent the implicit validation.
- **numeric** (int): A numeric representation of the IBAN.
- **formatted** (str): The IBAN formatted in blocks of 4 digits.
- **spec** (dict): The country specific IBAN specification.
- **bic** (BIC | None): The BIC associated to the IBAN's bank-code. Returns ``None`` if no appropriate :class:`BIC` can be constructed.
- **country** (Country | None): The country this IBAN is registered in.
- **in_sepa_zone** (bool): Is the country in the Single Euro Payments Area (SEPA) zone.
- **country_code** (str): ISO 3166 alpha-2 country code.
- **checksum_digits** (str): Two digit checksum of the BBAN.
- **national_checksum_digits** (str): National checksum digits.
- **bank_code** (str): The country specific bank-code.
- **branch_code** (str): The branch-code of the bank if available.
- **account_code** (str): The domestic account-code.
- **account_id** (str): Holder specific account identification. This is currently only available for Brazil.
- **account_type** (str): Account type specifier. This value is only available for Seychelles, Brazil and Bulgaria.
- **account_holder_id** (str): Account holder's national identification. This value is only available for Iceland.
- **currency_code** (str): The account's currency code. This value is only available for Mauretania, Seychelles and Guatemala.
- **bank** (dict | None): The information of the bank related to the bank code as part of the BBAN.
- **bank_name** (str | None): The name of the bank associated with the IBAN bank code.
- **bank_short_name** (str | None): The name of the bank associated with the IBAN bank code.
```

--------------------------------

### IBAN.from_bban

Source: https://schwifty.readthedocs.io/en/latest/_modules/schwifty/iban.html

Creates an IBAN object from a country code and a BBAN object. It allows for specifying bank code, branch code, account code, and other country-specific fields.

```APIDOC
## IBAN.from_bban

### Description
Creates an IBAN object from a country code and a BBAN object. It allows for specifying bank code, branch code, account code, and other country-specific fields.

### Method
`classmethod`

### Parameters
#### Path Parameters
- **country_code** (str) - Required - The ISO 3166 alpha-2 country code.
- **bank_code** (str) - Required - The country specific bank-code.
- **branch_code** (str) - Optional - The country specific branch code.
- **account_code** (str) - Required - The customer specific account-code.
- **kwargs** (str) - Optional - Additional country specific fields.

### Raises
- `InvalidAccountCode`: If the account code does not meet the national requirements.

### Version Changed
- 2020.08.3: Added the `branch_code` parameter.
- 2021.05.2: Added support for generating the country specific checksum of the BBAN for Belgian banks.
```
Tokens:
Raw