ciuy

Package for validating Uruguayan identity document numbers.

The functions in this package work with strings and ignore any non-digit characters. Numbers are valid too. So for example, the following expressions represent the same document number:

'1.234.567-2'
'12345672'
12345672

Installation

ciuy can be installed with pip:

Usage

>>> import ciuy
>>> ciuy.validate_ci("1.234.567-2")
True
>>> ciuy.validation_digit("1.234.567")
'2'
>>> ciuy.random()
'82405816'

See Functions and examples for more detailed documentation of each function.

Testing

This package includes some doctests, as well as unit tests that can be run with pytest.

After cloning the repository, you can run the doctests with:

$ python3 -m doctest ./ciuy/__init__.py -v
(several lines ommited)
11 passed and 0 failed.
Test passed.

Use pytest to run the unit tests:

$ py.test
============================= test session starts ==============================
platform linux -- Python 3.8.1, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
rootdir: /home/ciuy
collected 98 items

tests\test_clean.py ..........                                           [ 10%]
tests\test_command_line.py ........................                      [ 34%]
tests\test_random_ci.py ..                                               [ 36%]
tests\test_validate_ci.py .......................................        [ 76%]
tests\test_validation_digit.py .......................                   [100%]

============================== 98 passed in 1.09s =============================

You can also use pytest to run all tests, including doctests, with:

$ py.test --doctest-modules

Command line

After installation, the following commands become available:

$ validate_ci 1.234.567-2
True
$ validation_digit 1.234.567
2
$ random_ci
82405816

Functions and examples

ciuy.validate_ci(ci)

Validates the document number passed as a paremeter.

Parameters:ci (str) – The document number to validate. Any non-digit characters are ignored. A number can be passed as a parameter as well. Returns:True if the document number is valid, False otherwise. Return type:bool Raises:ValueError – if ci, without including the validation digit, is lower than 100.000 or higher than 9.999.999.

>>> ciuy.validate_ci(1.234.567-2)
True

ciuy.validation_digit(ci)

Returns the validation digit for a given document number.

Parameters:ci (str) – The document number for which one wants to find the validation digit. Any non-digit characters are ignored. A number can be passed as a parameter as well. Returns:The validation digit. Return type:bool Raises:ValueError – if ciis lower than 100.000 or higher than 9.999.999.

>>> ciuy.validation_digit(1.234.567)
'2'

ciuy.random()

Returns a random document number, including validation digit. The document number is in the (100.000, 9.999.999) range.

Returns:A random valid document number. Return type:str

>>> ciuy.random()
'82405816'

About Uruguayan id numbers

In Uruguay, each person is issued an identity card, which contains all the necessary information to identify the owner unequivocally.

This document is mandatory for all inhabitants Uruguay, whether they are native citizens, legal citizens, or resident aliens in the country, even for children as young as 45 days old.

Sample Uruguayan id card.

Each person is issued an identiy number (which is decided at birth for native citizens), which contains 7 digits and a validation number. Old identity number contain only 6 digits, and a validation number.

Calculating the validation number

In order to calculate the validation number for a 7-digit id number, the number must be multiplied, digit by digit, by 8123476. Then the result is added. So if the number is interpreted as a 7 dimensional vector, one must calculate the dot product of said vector by <8, 1, 2, 3, 4, 7, 6>.

Then, if the resulting number is n, the validation digit will be n modulo 10.

Validating 6-digit numbers

6 digit numbers should be multiplied by <1, 2, 3, 4, 7, 6>instead. Given n, the resulting number, then the validation digit will be n modulo 10.

An example

Validating 1.234.567:

\[\begin{split}&<1, 2, 3, 4, 5, 6, 7> . <8, 1, 2, 3, 4, 7, 6> = \\ &\; 1*8 + 2*1 + 3*2 + 4*3 + 5*4 + 6*7 + 7*6 = 132\\ &\\ &132 \: mod \: 10 = 2\end{split}\]

So the validation digit is 2. The id number would normally be written as 1.234.567-2.