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: str) → str¶

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: str) → bool¶

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: str) → str¶

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: str) → str¶

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: str) → int¶

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: str) → str¶

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: str, name: str) → NumberValidationModule | None¶

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.eid`	eID Number (Belgian electronic Identity Card Number).
`be.iban`	Belgian IBAN (International Bank Account Number).
`be.nn`	NN, NISS, RRN (Belgian national number).
`be.ssn`	SSN, INSZ, NISS (Belgian social security 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.cae`	CAE (Código de Actividad y Establecimiento, Spanish activity establishment code).
`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.nik`	NIK (Nomor Induk Kependudukan, Indonesian identity 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).
`isni`	ISNI (International Standard Name Identifier).
`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).
`jp.in_`	IN (個人番号, kojin bangō, Japanese Individual 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.identiteitskaartnummer`	Identiteitskaartnummer, Paspoortnummer (the Dutch passport 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).
`ru.ogrn`	ОГРН, OGRN, PSRN, ОГРНИП, OGRNIP (Russian Primary State Registration Number).
`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

Contributing to python-stdnum¶

Contributing to python-stdnum