python-stdnum

A Python module to parse, validate and reformat standard numbers and codes in different formats. It contains a large collection of number formats.

Basically any number or code that has some validation mechanism available or some common formatting is eligible for inclusion in this library.

https://arthurdejong.org/python-stdnum/

Common Interface

Most of the number format modules implement the following functions:

module.validate(number)

Validate the number and return a compact, consistent representation of the number or code. If the validation fails, an exception is raised that indicates the type of error.

Raises:

ValidationError – When the specified number is invalid

Returns:

str – A compact (canonical) representation of the number

module.is_valid(number)

Return either True or False depending on whether the passed number is in any supported and valid form and passes all embedded checks of the number. This function should never raise an exception.

Returns:

bool – True if validated, False otherwise

module.compact(number)

Return a compact representation of the number or code. This function generally does not do validation but may raise exceptions for wildly invalid numbers.

Returns:

str – The compacted number

module.format(number)

Return a formatted version of the number in the preferred format. This function generally expects to be passed a valid number or code and may raise exceptions for invalid numbers.

Returns:

str – A formatted number

The check digit modules generally also provide the following functions:

module.checksum(number)

Calculate the checksum over the provided number. This is generally a number that can be used to determine whether the provided number is valid. It depends on the algorithm which checksum is considered valid.

Returns:

int – A numeric checksum over the number

module.calc_check_digit(number)

Calculate the check digit that should be added to the number to make it valid.

Returns:

str – A check digit that can be appended

Apart from the above, the modules may add extra parsing, validation or conversion functions.

Helper functions and modules

exceptions

Collection of exceptions.

stdnum.get_cc_module(cc, name)

Find the country-specific named module.

Searches the stdnum collection of modules for a number format for a particular country. name may be an aliased name. For example:

>>> from stdnum import get_cc_module
>>> mod = get_cc_module('nl', 'vat')
>>> mod
<module 'stdnum.nl.btw' from '...'>
>>> mod.validate('004495445B01')
'004495445B01'

Will return None if no module could be found. The generic names that are currently in use:

• 'vat' for value added tax numbers

• 'businessid' for generic business identifiers (although some countries may have multiple)

• 'personalid' for generic personal identifiers (some countries may have multiple, especially for tax purposes)

• 'postal_code' for address postal codes

Generic check digit algorithms

damm	The Damm algorithm.
iso7064	Collection of the ISO 7064 algorithms.
luhn	The Luhn and Luhn mod N algorithms.
verhoeff	The Verhoeff algorithm.

Available formats

ad.nrt	NRT (Número de Registre Tributari, Andorra tax number).
al.nipt	NIPT, NUIS (Numri i Identifikimit për Personin e Tatueshëm, Albanian tax number).
ar.cbu	CBU (Clave Bancaria Uniforme, Argentine bank account number).
ar.cuit	CUIT (Código Único de Identificación Tributaria, Argentinian tax number).
ar.dni	DNI (Documento Nacional de Identidad, Argentinian national identity nr.).
at.businessid	Austrian Company Register Numbers.
at.postleitzahl	Postleitzahl (Austrian postal code).
at.tin	Abgabenkontonummer (Austrian tax identification number).
at.uid	UID (Umsatzsteuer-Identifikationsnummer, Austrian VAT number).
at.vnr	VNR, SVNR, VSNR (Versicherungsnummer, Austrian social security number).
au.abn	ABN (Australian Business Number).
au.acn	ACN (Australian Company Number).
au.tfn	TFN (Australian Tax File Number).
be.bis	BIS (Belgian BIS number).
be.iban	Belgian IBAN (International Bank Account Number).
be.nn	NN, NISS, RRN (Belgian national number).
be.vat	BTW, TVA, NWSt, ondernemingsnummer (Belgian enterprise number).
bg.egn	EGN (ЕГН, Единен граждански номер, Bulgarian personal identity codes).
bg.pnf	PNF (ЛНЧ, Личен номер на чужденец, Bulgarian number of a foreigner).
bg.vat	VAT (Идентификационен номер по ДДС, Bulgarian VAT number).
bic	BIC (ISO 9362 Business identifier codes).
bitcoin	Bitcoin address.
br.cnpj	CNPJ (Cadastro Nacional da Pessoa Jurídica, Brazilian company identifier).
br.cpf	CPF (Cadastro de Pessoas Físicas, Brazilian national identifier).
by.unp	УНП, UNP (Учетный номер плательщика, the Belarus VAT number).
ca.bc_phn	BC PHN (British Columbia Personal Health Number).
ca.bn	BN (Canadian Business Number).
ca.sin	SIN (Canadian Social Insurance Number).
casrn	CAS RN (Chemical Abstracts Service Registry Number).
cfi	CFI (ISO 10962 Classification of Financial Instruments).
ch.esr	ESR, ISR, QR-reference (reference number on Swiss payment slips).
ch.ssn	Swiss social security number ("Sozialversicherungsnummer").
ch.uid	UID (Unternehmens-Identifikationsnummer, Swiss business identifier).
ch.vat	VAT, MWST, TVA, IVA, TPV (Mehrwertsteuernummer, the Swiss VAT number).
cl.rut	RUT (Rol Único Tributario, Chilean national tax number).
cn.ric	RIC No.
cn.uscc	USCC (Unified Social Credit Code, 统一社会信用代码, China tax number).
co.nit	NIT (Número De Identificación Tributaria, Colombian identity code).
cr.cpf	CPF (Cédula de Persona Física, Costa Rica physical person ID number).
cr.cpj	CPJ (Cédula de Persona Jurídica, Costa Rica tax number).
cr.cr	CR (Cédula de Residencia, Costa Rica foreigners ID number).
cu.ni	NI (Número de identidad, Cuban identity card numbers).
cusip	CUSIP number (financial security identification number).
cy.vat	Αριθμός Εγγραφής Φ.Π.Α.
cz.bankaccount	Czech bank account number.
cz.dic	DIČ (Daňové identifikační číslo, Czech VAT number).
cz.rc	RČ (Rodné číslo, the Czech birth number).
de.handelsregisternummer	Handelsregisternummer (German company register number).
de.idnr	IdNr (Steuerliche Identifikationsnummer, German personal tax number).
de.stnr	St.-Nr.
de.vat	Ust ID Nr.
de.wkn	Wertpapierkennnummer (German securities identification code).
dk.cpr	CPR (personnummer, the Danish citizen number).
dk.cvr	CVR (Momsregistreringsnummer, Danish VAT number).
do.cedula	Cedula (Dominican Republic national identification number).
do.ncf	NCF (Números de Comprobante Fiscal, Dominican Republic receipt number).
do.rnc	RNC (Registro Nacional del Contribuyente, Dominican Republic tax number).
dz.nif	NIF, sometimes N.I.F.
ean	EAN (International Article Number).
ec.ci	CI (Cédula de identidad, Ecuadorian personal identity code).
ec.ruc	RUC (Registro Único de Contribuyentes, Ecuadorian company tax number).
ee.ik	Isikukood (Estonian Personal ID number).
ee.kmkr	KMKR (Käibemaksukohuslase, Estonian VAT number).
ee.registrikood	Registrikood (Estonian organisation registration code).
eg.tn	Tax Registration Number (الرقم الضريبي, Egypt tax number).
es.ccc	CCC (Código Cuenta Corriente, Spanish Bank Account Code)
es.cif	CIF (Código de Identificación Fiscal, Spanish company tax number).
es.cups	CUPS (Código Unificado de Punto de Suministro, Spanish meter point number).
es.dni	DNI (Documento Nacional de Identidad, Spanish personal identity codes).
es.iban	Spanish IBAN (International Bank Account Number).
es.nie	NIE (Número de Identificación de Extranjero, Spanish foreigner number).
es.nif	NIF (Número de Identificación Fiscal, Spanish VAT number).
es.postal_code	Postcode (the Spanish postal code).
es.referenciacatastral	Referencia Catastral (Spanish real estate property id)
eu.at_02	SEPA Identifier of the Creditor (AT-02).
eu.banknote	Euro banknote serial numbers.
eu.ecnumber	EC Number (European Community number).
eu.eic	EIC (European Energy Identification Code).
eu.nace	NACE (classification for businesses in the European Union).
eu.oss	OSS (European VAT on e-Commerce - One Stop Shop).
eu.vat	VAT (European Union VAT number).
fi.alv	ALV nro (Arvonlisäveronumero, Finnish VAT number).
fi.associationid	Finnish Association Identifier.
fi.hetu	HETU (Henkilötunnus, Finnish personal identity code).
fi.veronumero	Veronumero (Finnish individual tax number).
fi.ytunnus	Y-tunnus (Finnish business identifier).
figi	FIGI (Financial Instrument Global Identifier).
fo.vn	V-number (Vinnutal, Faroe Islands tax number).
fr.nif	NIF (Numéro d'Immatriculation Fiscale, French tax identification number).
fr.nir	NIR (French personal identification number).
fr.siren	SIREN (a French company identification number).
fr.siret	SIRET (a French company establishment identification number).
fr.tva	n° TVA (taxe sur la valeur ajoutée, French VAT number).
gb.nhs	NHS (United Kingdom National Health Service patient identifier).
gb.sedol	SEDOL number (Stock Exchange Daily Official List number).
gb.upn	UPN (English Unique Pupil Number).
gb.utr	UTR (United Kingdom Unique Taxpayer Reference).
gb.vat	VAT (United Kingdom (and Isle of Man) VAT registration number).
gh.tin	TIN (Taxpayer Identification Number, Ghana tax number).
gn.nifp	NIFp (Numéro d'Identification Fiscale Permanent, Guinea tax number).
gr.amka	AMKA (Αριθμός Μητρώου Κοινωνικής Ασφάλισης, Greek social security number).
gr.vat	FPA, ΦΠΑ, ΑΦΜ (Αριθμός Φορολογικού Μητρώου, the Greek VAT number).
grid	GRid (Global Release Identifier).
gs1_128	GS1-128 (Standard to encode product information in Code 128 barcodes).
gt.nit	NIT (Número de Identificación Tributaria, Guatemala tax number).
hr.oib	OIB (Osobni identifikacijski broj, Croatian identification number).
hu.anum	ANUM (Közösségi adószám, Hungarian VAT number).
iban	IBAN (International Bank Account Number).
id.npwp	NPWP (Nomor Pokok Wajib Pajak, Indonesian VAT Number).
ie.pps	PPS No (Personal Public Service Number, Irish personal number).
ie.vat	VAT (Irish tax reference number).
il.hp	Company Number (מספר חברה, or short ח.פ.
il.idnr	Identity Number (Mispar Zehut, מספר זהות, Israeli identity number).
imei	IMEI (International Mobile Equipment Identity).
imo	IMO number (International Maritime Organization number).
imsi	IMSI (International Mobile Subscriber Identity).
in_.aadhaar	Aadhaar (Indian personal identity number).
in_.epic	EPIC (Electoral Photo Identity Card, Indian Voter ID).
in_.gstin	GSTIN (Goods and Services Tax identification number, Indian VAT number).
in_.pan	PAN (Permanent Account Number, Indian income tax identifier).
in_.vid	VID (Indian personal virtual identity number).
is_.kennitala	Kennitala (Icelandic personal and organisation identity code).
is_.vsk	VSK number (Virðisaukaskattsnúmer, Icelandic VAT number).
isan	ISAN (International Standard Audiovisual Number).
isbn	ISBN (International Standard Book Number).
isil	ISIL (International Standard Identifier for Libraries).
isin	ISIN (International Securities Identification Number).
ismn	ISMN (International Standard Music Number).
iso11649	ISO 11649 (Structured Creditor Reference).
iso6346	ISO 6346 (International standard for container identification)
isrc	ISRC (International Standard Recording Code).
issn	ISSN (International Standard Serial Number).
it.aic	AIC (Italian code for identification of drugs).
it.codicefiscale	Codice Fiscale (Italian tax code for individuals).
it.iva	Partita IVA (Italian VAT number).
jp.cn	CN (法人番号, hōjin bangō, Japanese Corporate Number).
ke.pin	PIN (Personal Identification Number, Kenya tax number).
kr.brn	BRN (사업자 등록 번호, South Korea Business Registration Number).
kr.rrn	RRN (South Korean resident registration number).
lei	LEI (Legal Entity Identifier).
li.peid	PEID (Liechtenstein tax code for individuals and entities).
lt.asmens	Asmens kodas (Lithuanian, personal numbers).
lt.pvm	PVM (Pridėtinės vertės mokestis mokėtojo kodas, Lithuanian VAT number).
lu.tva	TVA (taxe sur la valeur ajoutée, Luxembourgian VAT number).
lv.pvn	PVN (Pievienotās vērtības nodokļa, Latvian VAT number).
ma.ice	ICE (Identifiant Commun de l’Entreprise, التعريف الموحد للمقاولة, Morocco tax number).
mac	MAC address (Media Access Control address).
mc.tva	n° TVA (taxe sur la valeur ajoutée, Monacan VAT number).
md.idno	IDNO (Moldavian company identification number).
me.iban	Montenegro IBAN (International Bank Account Number).
me.pib	PIB (Poreski Identifikacioni Broj, Montenegro tax number).
meid	MEID (Mobile Equipment Identifier).
mk.edb	ЕДБ (Едниствен Даночен Број, North Macedonia tax number).
mt.vat	VAT (Maltese VAT number).
mu.nid	ID number (Mauritian national identifier).
mx.curp	CURP (Clave Única de Registro de Población, Mexican personal ID).
mx.rfc	RFC (Registro Federal de Contribuyentes, Mexican tax number).
my.nric	NRIC No.
nl.brin	BRIN number (the Dutch school identification number).
nl.bsn	BSN (Burgerservicenummer, the Dutch citizen identification number).
nl.btw	Btw-identificatienummer (Omzetbelastingnummer, the Dutch VAT number).
nl.onderwijsnummer	Onderwijsnummer (the Dutch student identification number).
nl.postcode	Postcode (the Dutch postal code).
no.fodselsnummer	Fødselsnummer (Norwegian birth number, the national identity number).
no.iban	Norwegian IBAN (International Bank Account Number).
no.kontonr	Konto nr.
no.mva	MVA (Merverdiavgift, Norwegian VAT number).
no.orgnr	Orgnr (Organisasjonsnummer, Norwegian organisation number).
nz.bankaccount	New Zealand bank account number
nz.ird	IRD number (New Zealand Inland Revenue Department (Te Tari Tāke) number).
pe.cui	CUI (Cédula Única de Identidad, Peruvian identity number).
pe.ruc	RUC (Registro Único de Contribuyentes, Peruvian company tax number).
pk.cnic	CNIC number (Pakistani Computerised National Identity Card number).
pl.nip	NIP (Numer Identyfikacji Podatkowej, Polish VAT number).
pl.pesel	PESEL (Polish national identification number).
pl.regon	REGON (Rejestr Gospodarki Narodowej, Polish register of economic units).
pt.cc	CC (Número de Cartão de Cidadão, Portuguese Identity number).
pt.nif	NIF (Número de identificação fiscal, Portuguese VAT number).
py.ruc	RUC number (Registro Único de Contribuyentes, Paraguay tax number).
ro.cf	CF (Cod de înregistrare în scopuri de TVA, Romanian VAT number).
ro.cnp	CNP (Cod Numeric Personal, Romanian Numerical Personal Code).
ro.cui	CUI or CIF (Codul Unic de Înregistrare, Romanian company identifier).
ro.onrc	ONRC (Ordine din Registrul Comerţului, Romanian Trade Register identifier).
rs.pib	PIB (Poreski Identifikacioni Broj, Serbian tax identification number).
ru.inn	ИНН (Идентификационный номер налогоплательщика, Russian tax identifier).
se.orgnr	Orgnr (Organisationsnummer, Swedish company number).
se.personnummer	Personnummer (Swedish personal identity number).
se.postnummer	Postcode (the Swedish postal code).
se.vat	VAT (Moms, Mervärdesskatt, Swedish VAT number).
sg.uen	UEN (Singapore's Unique Entity Number).
si.ddv	ID za DDV (Davčna številka, Slovenian VAT number).
si.emso	Enotna matična številka občana (Unique Master Citizen Number).
si.maticna	Matična številka poslovnega registra (Corporate Registration Number)
sk.dph	IČ DPH (IČ pre daň z pridanej hodnoty, Slovak VAT number).
sk.rc	RČ (Rodné číslo, the Slovak birth number).
sm.coe	COE (Codice operatore economico, San Marino national tax number).
sv.nit	NIT (Número de Identificación Tributaria, El Salvador tax number).
th.moa	MOA (Thailand Memorandum of Association Number).
th.pin	PIN (Thailand Personal Identification Number).
th.tin	TIN (Thailand Taxpayer Identification Number).
tn.mf	MF (Matricule Fiscal, Tunisia tax number).
tr.tckimlik	T.C.
tr.vkn	VKN (Vergi Kimlik Numarası, Turkish tax identification number).
tw.ubn	UBN (Unified Business Number, 統一編號, Taiwanese tax number).
ua.edrpou	ЄДРПОУ, EDRPOU (Identifier for enterprises and organizations in Ukraine).
ua.rntrc	РНОКПП, RNTRC (Individual taxpayer registration number in Ukraine).
us.atin	ATIN (U.S.
us.ein	EIN (U.S.
us.itin	ITIN (U.S.
us.ptin	PTIN (U.S.
us.rtn	RTN (Routing transport number).
us.ssn	SSN (U.S.
us.tin	TIN (U.S.
uy.rut	RUT (Registro Único Tributario, Uruguay tax number).
vatin	VATIN (International value added tax identification number)
ve.rif	RIF (Registro de Identificación Fiscal, Venezuelan VAT number).
vn.mst	MST (Mã số thuế, Vietnam tax number).
za.idnr	ID number (South African Identity Document number).
za.tin	TIN (South African Tax Identification Number).

Changes in python-stdnum

• Changes in python-stdnum
  • changes from 1.19 to 1.20
  • changes from 1.18 to 1.19
  • changes from 1.17 to 1.18
  • changes from 1.16 to 1.17
  • changes from 1.15 to 1.16
  • changes from 1.14 to 1.15
  • changes from 1.13 to 1.14
  • changes from 1.12 to 1.13
  • changes from 1.11 to 1.12
  • changes from 1.10 to 1.11
  • changes from 1.9 to 1.10
  • changes from 1.8.1 to 1.9
  • changes from 1.8 to 1.8.1
  • changes from 1.7 to 1.8
  • changes from 1.6 to 1.7
  • changes from 1.5 to 1.6
  • changes from 1.4 to 1.5
  • changes from 1.3 to 1.4
  • changes from 1.2 to 1.3
  • changes from 1.1 to 1.2
  • changes from 1.0 to 1.1
  • changes from 0.9 to 1.0
  • changes from 0.8.1 to 0.9
  • changes from 0.8 to 0.8.1
  • changes from 0.7 to 0.8
  • changes from 0.6 to 0.7
  • changes from 0.5 to 0.6
  • changes from 0.4 to 0.5
  • changes from 0.3 to 0.4
  • changes from 0.2 to 0.3
  • changes from 0.1 to 0.2

Contributing to python-stdnum

• Contributing to python-stdnum
  • Adding number formats
  • Code contributions
  • Testing
  • Finding test numbers
  • Reverse engineering
  • Registries