|
| 1 | +# isin.py - functions for handling ISIN numbers |
| 2 | +# |
| 3 | +# Copyright (C) 2015 Arthur de Jong |
| 4 | +# |
| 5 | +# This library is free software; you can redistribute it and/or |
| 6 | +# modify it under the terms of the GNU Lesser General Public |
| 7 | +# License as published by the Free Software Foundation; either |
| 8 | +# version 2.1 of the License, or (at your option) any later version. |
| 9 | +# |
| 10 | +# This library is distributed in the hope that it will be useful, |
| 11 | +# but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 13 | +# Lesser General Public License for more details. |
| 14 | +# |
| 15 | +# You should have received a copy of the GNU Lesser General Public |
| 16 | +# License along with this library; if not, write to the Free Software |
| 17 | +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
| 18 | +# 02110-1301 USA |
| 19 | + |
| 20 | +"""ISIN (International Securities Identification Number). |
| 21 | +
|
| 22 | +The ISIN is a 12-character alpha-numerical code specified in ISO 6166 used to |
| 23 | +identify exchange listed securities such as bonds, commercial paper, stocks |
| 24 | +and warrants. The number is formed of a two-letter country code, a nine |
| 25 | +character national security identifier and a single check digit. |
| 26 | +
|
| 27 | +This module does not currently separately validate the embedded national |
| 28 | +security identifier part (e.g. when it is a CUSIP). |
| 29 | +
|
| 30 | +More information: |
| 31 | + https://en.wikipedia.org/wiki/International_Securities_Identification_Number |
| 32 | +
|
| 33 | +>>> validate('US0378331005') |
| 34 | +'US0378331005' |
| 35 | +>>> validate('US0378331003') |
| 36 | +Traceback (most recent call last): |
| 37 | + ... |
| 38 | +InvalidChecksum: ... |
| 39 | +""" |
| 40 | + |
| 41 | +from stdnum.exceptions import * |
| 42 | +from stdnum.util import clean |
| 43 | + |
| 44 | + |
| 45 | +# all valid ISO 3166-1 alpha-2 country codes |
| 46 | +_iso_3116_1_country_codes = [ |
| 47 | + 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', |
| 48 | + 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', |
| 49 | + 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', |
| 50 | + 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', |
| 51 | + 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', |
| 52 | + 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', |
| 53 | + 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', |
| 54 | + 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', |
| 55 | + 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', |
| 56 | + 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', |
| 57 | + 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', |
| 58 | + 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', |
| 59 | + 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', |
| 60 | + 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', |
| 61 | + 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', |
| 62 | + 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', |
| 63 | + 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', |
| 64 | + 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', |
| 65 | + 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', |
| 66 | + 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', |
| 67 | + 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW'] |
| 68 | + |
| 69 | +# the special XS country code is for international securities |
| 70 | +# substitute agencies can allocate an ISIN starting with XA (CUSIP Global |
| 71 | +# Services), XB (NSD Russia), XC (WM Datenservice Germany) or XD (SIX |
| 72 | +# Telekurs). |
| 73 | +_country_codes = set(_iso_3116_1_country_codes + [ |
| 74 | + 'XS', 'EU', 'XA', 'XB', 'XC', 'XD']) |
| 75 | + |
| 76 | +# the letters allowed in an ISIN |
| 77 | +_alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ' |
| 78 | + |
| 79 | + |
| 80 | +def compact(number): |
| 81 | + """Convert the number to the minimal representation. This strips the |
| 82 | + number of any valid separators and removes surrounding whitespace.""" |
| 83 | + return clean(number, ' ').strip().upper() |
| 84 | + |
| 85 | + |
| 86 | +def calc_check_digit(number): |
| 87 | + """Calculate the check digits for the number.""" |
| 88 | + # convert to numeric first, then double some, then sum individual digits |
| 89 | + number = ''.join(str(_alphabet.index(n)) for n in number) |
| 90 | + number = ''.join( |
| 91 | + str(int(n) * (2 - i % 2)) for i, n in enumerate(reversed(number))) |
| 92 | + return str((10 - sum(int(n) for n in number)) % 10) |
| 93 | + |
| 94 | + |
| 95 | +def validate(number): |
| 96 | + """Checks to see if the number provided is valid. This checks the length |
| 97 | + and check digit.""" |
| 98 | + number = compact(number) |
| 99 | + if not all(x in _alphabet for x in number): |
| 100 | + raise InvalidFormat() |
| 101 | + if len(number) != 12: |
| 102 | + raise InvalidLength() |
| 103 | + if number[:2] not in _country_codes: |
| 104 | + raise InvalidComponent() |
| 105 | + if calc_check_digit(number[:-1]) != number[-1]: |
| 106 | + raise InvalidChecksum() |
| 107 | + return number |
| 108 | + |
| 109 | + |
| 110 | +def is_valid(number): |
| 111 | + """Checks to see if the number provided is valid. This checks the length |
| 112 | + and check digit.""" |
| 113 | + try: |
| 114 | + return bool(validate(number)) |
| 115 | + except ValidationError: |
| 116 | + return False |
0 commit comments