Arthur de Jong

Open Source / Free Software developer

summaryrefslogtreecommitdiffstats
path: root/docs/index.rst
blob: 00a033b9ce38fac76e86b719ef5c6b657c137f6f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
.. module:: stdnum

.. include:: ../README.md
   :end-before: Available formats


Common Interface
----------------

Most of the number format modules implement the following functions:

.. function:: module.validate(number)

   Validate the number and return a compact, consistent representation of
   the number or code. If the validation fails,
   :mod:`an exception <.exceptions>` 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

.. function:: 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

.. function:: 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

.. function:: 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:

.. function:: 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

.. function:: 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
----------------------------

.. autosummary::
   :toctree:

   exceptions

.. autofunction:: get_cc_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
------------------------------

.. autosummary::
   :toctree:

   damm
   iso7064
   luhn
   verhoeff


Available formats
-----------------

.. autosummary::
   :toctree:

   ad.nrt
   al.nipt
   ar.cbu
   ar.cuit
   ar.dni
   at.businessid
   at.postleitzahl
   at.tin
   at.uid
   at.vnr
   au.abn
   au.acn
   au.tfn
   be.bis
   be.iban
   be.nn
   be.vat
   bg.egn
   bg.pnf
   bg.vat
   bic
   bitcoin
   br.cnpj
   br.cpf
   by.unp
   ca.bn
   ca.sin
   casrn
   cfi
   ch.esr
   ch.ssn
   ch.uid
   ch.vat
   cl.rut
   cn.ric
   cn.uscc
   co.nit
   cr.cpf
   cr.cpj
   cr.cr
   cu.ni
   cusip
   cy.vat
   cz.bankaccount
   cz.dic
   cz.rc
   de.handelsregisternummer
   de.idnr
   de.stnr
   de.vat
   de.wkn
   dk.cpr
   dk.cvr
   do.cedula
   do.ncf
   do.rnc
   dz.nif
   ean
   ec.ci
   ec.ruc
   ee.ik
   ee.kmkr
   ee.registrikood
   eg.tn
   es.ccc
   es.cif
   es.cups
   es.dni
   es.iban
   es.nie
   es.nif
   es.postal_code
   es.referenciacatastral
   eu.at_02
   eu.banknote
   eu.eic
   eu.nace
   eu.oss
   eu.vat
   fi.alv
   fi.associationid
   fi.hetu
   fi.veronumero
   fi.ytunnus
   figi
   fo.vn
   fr.nif
   fr.nir
   fr.siren
   fr.siret
   fr.tva
   gb.nhs
   gb.sedol
   gb.upn
   gb.utr
   gb.vat
   gh.tin
   gn.nifp
   gr.amka
   gr.vat
   grid
   gs1_128
   gt.nit
   hr.oib
   hu.anum
   iban
   id.npwp
   ie.pps
   ie.vat
   il.hp
   il.idnr
   imei
   imo
   imsi
   in_.aadhaar
   in_.epic
   in_.gstin
   in_.pan
   is_.kennitala
   is_.vsk
   isan
   isbn
   isil
   isin
   ismn
   iso11649
   iso6346
   isrc
   issn
   it.aic
   it.codicefiscale
   it.iva
   jp.cn
   ke.pin
   kr.brn
   kr.rrn
   lei
   li.peid
   lt.asmens
   lt.pvm
   lu.tva
   lv.pvn
   ma.ice
   mac
   mc.tva
   md.idno
   me.iban
   me.pib
   meid
   mk.edb
   mt.vat
   mu.nid
   mx.curp
   mx.rfc
   my.nric
   nl.brin
   nl.bsn
   nl.btw
   nl.onderwijsnummer
   nl.postcode
   no.fodselsnummer
   no.iban
   no.kontonr
   no.mva
   no.orgnr
   nz.bankaccount
   nz.ird
   pe.cui
   pe.ruc
   pk.cnic
   pl.nip
   pl.pesel
   pl.regon
   pt.cc
   pt.nif
   py.ruc
   ro.cf
   ro.cnp
   ro.cui
   ro.onrc
   rs.pib
   ru.inn
   se.orgnr
   se.personnummer
   se.postnummer
   se.vat
   sg.uen
   si.ddv
   si.emso
   si.maticna
   sk.dph
   sk.rc
   sm.coe
   sv.nit
   th.moa
   th.pin
   th.tin
   tn.mf
   tr.tckimlik
   tr.vkn
   tw.ubn
   ua.edrpou
   ua.rntrc
   us.atin
   us.ein
   us.itin
   us.ptin
   us.rtn
   us.ssn
   us.tin
   uy.rut
   vatin
   ve.rif
   vn.mst
   za.idnr
   za.tin


Changes in python-stdnum
------------------------

.. toctree::
   :maxdepth: 2

   changes


Contributing to python-stdnum
-----------------------------

.. toctree::
   :maxdepth: 2

   contributing