Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Developer Interface

## IBAN

class schwifty.IBAN(code: str, **kwargs: Any)

  The IBAN object.

  Examples

  You create a new IBAN object by supplying an IBAN code in text form. The IBAN is validated behind the scenes and you can then access all relevant components as properties:

      >>> iban = IBAN('DE89 3704 0044 0532 0130 00')
      >>> iban.account_code
      '0532013000'
      >>> iban.bank_code
      '37040044'
      >>> iban.country_code
      'DE'
      >>> iban.checksum_digits
      '89'

  Parameters:

    - iban (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.

    - InvalidLength – If the length does not match the country specific specification.

  Changed in version 2021.05.1: Added the validate_bban parameter that controls if the country specific checksum within the BBAN is also validated.

  Changed in version 2023.10.0: The `IBAN` is now a subclass of `str` and supports all its methods.

  classmethod generate(country_code: str, bank_code: str, account_code: str, branch_code: str = '') → IBAN

    Generate an IBAN from it’s components.

    If the bank-code and/or account-number have less digits than required by their country specific representation, the respective component is padded with zeros.

    Examples

    To generate an IBAN do the following:

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

    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.

    Changed in version 2020.08.3: Added the branch_code parameter to allow the branch code (or sort code) to be specified independently.

    Changed in version 2021.05.2: Added support for generating the country specific checksum of the BBAN for Belgian banks.

  validate(validate_bban: bool = False) → bool

    Validate the structural integrity of this IBAN.

    This function will verify the country specific format as well as the Luhn checksum in the 3rd and 4th position of the IBAN. For some countries (currently Belgium, Germany and Italy) it will also verify the correctness of the country specific checksum within the BBAN if the validate_bban parameter is set to True. For German banks it will pick the appropriate algorithm based on the bank code and verify that the account code has the correct checksum.

    Note

    You have to use the allow_invalid paramter when constructing the `IBAN`-object to circumvent the implicit validation.

    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.

      - InvalidLength – If the length does not match the country specific specification.

    Changed in version 2021.05.1: Added the validate_bban parameter that controls if the country specific checksum within the BBAN is also validated.

  property account_code: str

    The customer specific account-code

    Type:

      str

  property bank_code: str

    The country specific bank-code.

    Type:

      str

  property bank_name: str | None

    The name of the bank associated with the IBAN bank code.

    Examples

        >>> IBAN('DE89370400440532013000').bank_name
        'Commerzbank'

    New in version 2022.04.2.

    Type:

      str or None

  property bank_short_name: str | None

    The name of the bank associated with the IBAN bank code.

    Examples

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

    New in version 2022.04.2.

    Type:

      str or None

  property bban: str

    The BBAN part of the IBAN.

    Type:

      str

  property bic: BIC | None

    The BIC associated to the IBAN’s bank-code.

    If the bank code is not available in Schwifty’s registry `None` is returned.

    Changed in version 2020.08.1: Returns `None` if no appropriate `BIC` can be constructed.

    Type:

      BIC or None

  property branch_code: str

    The branch-code of the bank if available.

    Type:

      str or None

  property checksum_digits: str

    Two digit checksum of the IBAN.

    Type:

      str

  property country: Data | None

    The country this IBAN is registered in.

    Type:

      Country

  property country_code: str

    ISO 3166 alpha-2 country code.

    Type:

      str

  property formatted: str

    The IBAN formatted in blocks of 4 digits.

    Type:

      str

  property is_valid: bool

    Indicate if this is a valid IBAN.

    Note

    You have to use the allow_invalid paramter when constructing the `IBAN`-object to circumvent the implicit validation.

    Examples

        >>> IBAN('AB1234567890', allow_invalid=True).is_valid
        False

    New in version 2020.08.1.

    Type:

      bool

  property numeric: int

    A numeric represenation of the IBAN.

    Type:

      int

  property spec: dict[str, Any]

    The country specific IBAN specification.

    Type:

      dict

## BIC

class schwifty.BIC(code: str, **kwargs: Any)

  The BIC object.

  When creating an instance of a BIC the provided value is checked for correctnes, unless the `allow_invalid` parameter is set to `True`.

  The validation is done in the context of ISO 9362:2022, which allows numbers in the business party prefix (the first 4 chracters). If strict SWIFT compliance is required the `enforce_swift_compliance` parameter can be set to `True`, in which case numbers are disallowed as described in revision 2023 of the SWIFT BIC policy.

  Examples

  You can either create a new BIC object by providing a code as text:

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

  or by using the `from_bank_code()` classmethod:

      >>> bic = BIC.from_bank_code('DE', '43060967')
      >>> bic.formatted
      'GENO DE M1 GLS'

  Parameters:

    - bic (str) – The BIC value.

    - allow_invalid (bool) – If set to `True` validation is skipped on instantiation.

    - enforce_swift_commpliance (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.

  Changed in version 2023.10.0: The `BIC` is now a subclass of `str` and supports all its methods.

  Changed in version 2023.11.0: The validation of the `BIC` structure is now allowing numbers in the business party prefix, conforming to ISO 9362:2022. If strict SWIFT compliance should be ensured, the `enforce_swift_compliance` parameter can be set to `True`, which will then fall back to the previous validation method.

  classmethod candidates_from_bank_code(country_code: str, bank_code: str) → list[BIC]

    Create a list of potential BIC objects from country-code and domestic bank-code.

    Examples

        >>> bic_codes = BIC.candidates_from_bank_code("FR", "30004")
        >>> bic_codes
        [<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>]

        >>> BIC.candidates_from_bank_code("DE", "20070024")
        [<BIC=DEUTDEDBHAM>]

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

    Parameters:

      - country_code (str) – ISO 3166 alpha2 country-code.

      - bank_code (str) – Country specific bank-code.

    Returns:

      a list of BIC objects generated from the given country code and bank code.

    Return type:

      list[BIC]

    Raises:

      InvalidBankCode – If the given bank code wasn’t found in the registry

    Note

    This currently only works for selected countries. Amongst them

    - Austria

    - Belgium

    - Bulgaria

    - Croatia

    - Czech Republic

    - Finland

    - France

    - Germany

    - Great Britan

    - Hungary

    - Ireland

    - Latvia

    - Lithuania

    - Netherlands

    - Poland

    - Romania

    - Saudi Arabia

    - Slovakia

    - Slovenia

    - Spain

    - Sweden

    - Switzerland

  classmethod from_bank_code(country_code: str, bank_code: str) → BIC

    Create a new BIC object from country-code and domestic bank-code.

    Examples

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

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

    Parameters:

      - country_code (str) – ISO 3166 alpha2 country-code.

      - bank_code (str) – Country specific bank-code.

    Returns:

      a BIC object generated from the given country code and bank code.

    Return type:

      BIC

    Raises:

      InvalidBankCode – If the given bank code wasn’t found in the registry

    Note

    This currently only works for selected countries. Amongst them

    - Austria

    - Belgium

    - Bulgaria

    - Croatia

    - Czech Republic

    - Finland

    - France

    - Germany

    - Great Britan

    - Hungary

    - Ireland

    - Latvia

    - Lithuania

    - Netherlands

    - Poland

    - Romania

    - Saudi Arabia

    - Slovakia

    - Slovenia

    - Spain

    - Sweden

    - Switzerland

  validate(enforce_swift_compliance: bool = False) → bool

    Validate the structural integrity of this BIC.

    This function will verify the correct length, structure and the existence of the country code.

    Parameters:

      enforce_swift_commpliance (bool) – If set to `True` the stricter SWIFT BIC policy is applied, which disallows numbers in the business prefix.

    Note

    You have to use the allow_invalid paramter when constructing the `BIC`-object to circumvent the implicit validation.

    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.

  property bank_code: str

    The bank-code part of the BIC.

    Type:

      str

  property bank_name: str | None

    The name of the bank associated with the BIC.

    Deprecated since version 2020.01.0: Use `bank_names()` instead.

    Type:

      str or None

  property bank_names: list[str]

    The name of the banks associated with the BIC.

    Examples

        >>> BIC('MARKDEF1100').bank_names
        ['Bundesbank']

    New in version 2020.01.0.

    Type:

      List[str]

  property bank_short_name: str | None

    The short name of the bank associated with the BIC.

    Deprecated since version 2020.01.0: Use `bank_short_names()` instead.

    Type:

      str or None

  property bank_short_names: list[str]

    The short name of the banks associated with the BIC.

    Examples

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

    New in version 2020.01.0.

    Type:

      List[str]

  property branch_code: str

    The branch-code part of the BIC (if available)

    Type:

      str

  property country: Data | None

    The country this BIC is registered in.

    Type:

      Country

  property country_bank_code: str | None

    The country specific bank-code associated with the BIC.

    Deprecated since version 2020.01.0: Use `domestic_bank_codes()` instead.

    Type:

      str or None

  property country_code: str

    The ISO 3166 alpha2 country-code.

    Type:

      str

  property domestic_bank_codes: list[str]

    The country specific bank-codes associated with the BIC.

    Examples

        >>> BIC('MARKDEF1100').domestic_bank_codes
        ['10000000']

    New in version 2020.01.0.

    Type:

      List[str]

  property exists: bool

    Indicates if the BIC is available in Schwifty’s registry.

    Type:

      bool

  property formatted: str

    The BIC separated in the blocks bank-, country- and location-code.

    Examples

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

    Type:

      str

  property is_valid: bool

    Indicate if this is a valid BIC.

    Note

    You have to use the allow_invalid paramter when constructing the `BIC`-object to circumvent the implicit validation.

    Examples

        >>> BIC('FOOBARBAZ', allow_invalid=True).is_valid
        False

    New in version 2020.08.1.

    Type:

      bool

  property location_code: str

    The location code of the BIC.

    Type:

      str

  property type: str

    Indicates the type of BIC.

    This can be one of ‘testing’, ‘passive’, ‘reverse billing’ or ‘default’

    Examples

        >>> BIC('MARKDEF1100').type
        'passive'

    Returns:

      The BIC type.

    Return type:

      str

## Exceptions

exception schwifty.exceptions.InvalidAccountCode

  Indicates that the account code has an invalid strucutre.

exception schwifty.exceptions.InvalidBBANChecksum

  Indicates that the BBAN’s checksum is invalid.

exception schwifty.exceptions.InvalidBankCode

  Indicates that the bank code has an invalid structure.

exception schwifty.exceptions.InvalidBranchCode

  Indicates that the branch code has an invalid strucutre.

exception schwifty.exceptions.InvalidChecksumDigits

  Indicates that the IBAN’s checksum is invalid.

exception schwifty.exceptions.InvalidCountryCode

  Unknown country code in the input.

exception schwifty.exceptions.InvalidLength

  Indicates that the length of the input does not match the specifcation.

exception schwifty.exceptions.InvalidStructure

  Indicates a strctural error of the input (e.g. invalid characters).

exception schwifty.exceptions.SchwiftyException

  Base exception of all schwifty related errors.