feat: update Saudi modules (#43)

Read more: https://www.notion.so/gigapay/Saudi-Arabia-1a83b97583a080e48311ea94c9ebc250

Author: gustav

stdnum/sa/__init__.py

@@ -23,4 +23,4 @@
 # provide aliases
 from stdnum.sa import vat_number as vat  # noqa: F401
 from stdnum.sa import tin_number as business_tin  # noqa: F401
-from stdnum.sa import tin_number as personal_tin  # noqa: F401
+from stdnum.sa import nid as personal_tin  # noqa: F401

stdnum/sa/nid.py

@@ -0,0 +1,121 @@
+# nid.py - functions for handling Saudi Arabian National ID numbers
+# coding: utf-8
+#
+# Copyright (C) 2024
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 USA
+
+"""National ID (Saudi Arabian National ID or Iqama number).
+
+The Saudi Arabian National ID (for Saudi citizens, رقم الهوية الوطنية) or Iqama 
+(Residence ID for expatriates, الإقامة) serve as the tax ID for individuals when applicable.
+
+The number consists of 10 digits:
+- For Saudi citizens, it typically starts with 1 or 2
+- For resident expatriates (Iqama), it typically starts with 2
+- The number includes an internal check digit for validation
+
+For tax purposes, sometimes a 12-digit format is used:
+- First 2 digits: region code
+- Remaining 10 digits: the unique ID
+
+More information:
+* https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/
+
+>>> validate('1012345678')
+'1012345678'
+>>> validate('abcdefghij')  # doctest: +IGNORE_EXCEPTION_DETAIL
+Traceback (most recent call last):
+    ...
+InvalidComponent: ...
+>>> validate('10123456')  # doctest: +IGNORE_EXCEPTION_DETAIL
+Traceback (most recent call last):
+    ...
+InvalidLength: ...
+>>> format('101-234-5678')
+'1012345678'
+>>> format('1312345678901')
+'2345678901'
+>>> is_valid('1012345678')
+True
+>>> is_valid('131012345678')
+True
+"""
+
+from stdnum.exceptions import InvalidLength, InvalidComponent, ValidationError
+from stdnum.util import clean, isdigits
+
+
+def compact(number):
+    """Convert the number to the minimal representation.
+    
+    This strips the number of any valid separators and removes surrounding
+    whitespace.
+    """
+    return clean(number, ' -/').strip()
+
+
+def validate(number):
+    """Check if the number is a valid Saudi Arabian National ID or Iqama number.
+    
+    This checks the length and that all characters are digits.
+    The ID can be either 10 digits (standard format) or 12 digits (with region code).
+    For Saudi citizens, the ID typically starts with 1 or 2.
+    For resident expatriates (Iqama), the ID typically starts with 2.
+    """
+    number = compact(number)
+    
+    if len(number) == 12:
+        # If 12 digits (with region code), consider only the last 10 digits
+        number = number[2:]
+    
+    if len(number) != 10:
+        raise InvalidLength()
+    
+    if not isdigits(number):
+        raise InvalidComponent()
+    
+    first_digit = number[0]
+    if first_digit not in ('1', '2'):
+        raise InvalidComponent('National ID should start with 1 or 2')
+    
+    # Note: The specific check digit algorithm is not publicly documented,
+    # so we cannot implement a full validation here.
+    
+    return number
+
+
+def is_valid(number):
+    """Check if the number is a valid Saudi Arabian National ID or Iqama number."""
+    try:
+        return bool(validate(number))
+    except ValidationError:
+        return False
+
+
+def format(number):
+    """Format the number to the standard representation.
+    
+    If the number is 12 digits (with region code), return only the last 10 digits.
+    If the number is 13 digits, return only the last 10 digits.
+    Otherwise, return the compacted 10-digit number.
+    """
+    number = compact(number)
+    if len(number) == 12:
+        return number[2:]
+    elif len(number) == 13:
+        return number[3:]
+    return number

stdnum/sa/tin_number.py

@@ -18,19 +18,77 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 # 02110-1301 USA
 
-from stdnum.exceptions import InvalidLength, ValidationError
+"""TIN (Saudi Arabian Tax Identification Number).
+
+The Saudi Arabian Tax Identification Number (TIN), often referred to as the "Unique Number" 
+(الرقم المميز) is issued by ZATCA (Zakat, Tax and Customs Authority) to 
+taxpayer entities for tax and zakat purposes.
+
+The number consists of 10 digits:
+- First digit is 3 (indicating KSA's GCC country code)
+- Next 8 digits are a serial identifier
+- Last digit is a check digit
+
+More information:
+* https://web-archive.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Saudi-Arabia-TIN.pdf
+* https://zatca.gov.sa/
+
+>>> validate('3002707692')
+'3002707692'
+>>> validate('1234567890')  # doctest: +IGNORE_EXCEPTION_DETAIL
+Traceback (most recent call last):
+    ...
+InvalidComponent: ...
+>>> validate('300270769')  # doctest: +IGNORE_EXCEPTION_DETAIL
+Traceback (most recent call last):
+    ...
+InvalidLength: ...
+>>> format('300-270-7692')
+'3002707692'
+>>> is_valid('3002707692') 
+True
+"""
+
+from stdnum.exceptions import InvalidLength, InvalidComponent, ValidationError
+from stdnum.util import clean, isdigits
+
+
+def compact(number):
+    """Convert the number to the minimal representation.
+    
+    This strips the number of any valid separators and removes surrounding
+    whitespace.
+    """
+    return clean(number, ' -/').strip()
 
 
 def validate(number):
-    """Check if the number is valid. This checks the length."""
+    """Check if the number is a valid Saudi Arabian TIN number.
+    
+    This checks the length, first digit (must be 3 for KSA), and that
+    all characters are digits.
+    """
+    number = compact(number)
     if len(number) != 10:
         raise InvalidLength()
+    if not isdigits(number):
+        raise InvalidComponent()
+    if number[0] != '3':
+        raise InvalidComponent()
+    # Note: We would implement a check digit validation here if the specific
+    # algorithm was known. Currently, it's known that the last digit is a check
+    # digit, but the exact calculation method is not documented publicly.
     return number
 
 
 def is_valid(number):
-    """Check if the number is a valid."""
+    """Check if the number is a valid Saudi Arabian TIN number."""
     try:
         return bool(validate(number))
     except ValidationError:
         return False
+
+
+def format(number):
+    """Format the number to the standard representation."""
+    return compact(number)

stdnum/sa/vat_number.py

@@ -18,19 +18,94 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 # 02110-1301 USA
 
-from stdnum.exceptions import InvalidLength, ValidationError
+"""VAT (Kingdom of Saudi Arabia Value Added Tax number).
+
+The Saudi Arabian VAT number is a 15-digit number used for Value Added Tax
+purposes in Saudi Arabia. It incorporates the 10-digit Tax Identification
+Number (TIN) and adds 5 more digits with specific meanings.
+
+The structure is as follows:
+- First digit: GCC member state code (3 for Saudi Arabia)
+- Next 8 digits: Base serial number
+- Next 1 digit: Check digit (completes the 10-digit TIN)
+- Next 3 digits: Branch/establishment identifier (000 for headquarters, 
+  001, 002, etc. for branches)
+- Last 2 digits: Tax type identifier (01 for VAT)
+
+More information:
+* https://zatca.gov.sa/en/eServices/Pages/TaxpayerLookup.aspx
+
+>>> validate('300270769210001')
+'300270769210001'
+>>> validate('3002707692100')  # too short
+Traceback (most recent call last):
+    ...
+stdnum.exceptions.InvalidLength: The number has an invalid length.
+>>> validate('300270769X10001')  # invalid character
+Traceback (most recent call last):
+    ...
+stdnum.exceptions.InvalidFormat: The number has an invalid format.
+>>> is_valid('300270769210001')
+True
+>>> is_valid('400270769210001')  # should start with 3 for Saudi Arabia
+False
+>>> format('300270769210001')
+'3 00270769 2 100 01'
+"""
+
+from stdnum.exceptions import InvalidLength, InvalidFormat, ValidationError
+from stdnum.util import clean, isdigits
+
+
+def compact(number):
+    """Convert the number to the minimal representation.
+    
+    This strips the number of any valid separators and removes
+    surrounding whitespace.
+    """
+    return clean(number, ' -').strip()
 
 
 def validate(number):
-    """Check if the number is valid. This checks the length."""
+    """Check if the number is a valid Saudi Arabian VAT number.
+    
+    This checks the length, format, and basic country code.
+    """
+    number = compact(number)
     if len(number) != 15:
         raise InvalidLength()
+    if not isdigits(number):
+        raise InvalidFormat()
+    # First digit should be 3 for Saudi Arabia
+    if number[0] != '3':
+        raise InvalidFormat('First digit should be 3 for Saudi Arabia')
+    # Last two digits should be 01 for VAT
+    if number[-2:] != '01':
+        raise InvalidFormat('Last two digits should be 01 for VAT')
     return number
 
 
 def is_valid(number):
-    """Check if the number is a valid."""
+    """Check if the number is a valid Saudi Arabian VAT number."""
     try:
         return bool(validate(number))
     except ValidationError:
         return False
+
+
+def format(number):
+    """Format the number in the standard format.
+    
+    For a VAT number this would be: 3 00270769 2 100 01
+    (Country code, serial, check digit, branch, tax type)
+    """
+    number = compact(number)
+    if len(number) != 15:
+        raise InvalidLength()
+    return ' '.join([
+        number[0],       # Country code (3)
+        number[1:9],     # Base serial
+        number[9:10],    # Check digit
+        number[10:13],   # Branch identifier
+        number[13:15],   # Tax type
+    ])