Add accise - the French number for excise

Closes #424

Author: cedk

stdnum/eu/excise.py

@@ -70,7 +70,7 @@ def validate(number: str) -> str:
     if len(number) != 13:
         raise InvalidLength()
     module = _get_cc_module(number[:2])
-    if module:  # pragma: no cover (no implementation yet)
+    if module:
         module.validate(number)
     return number
 

stdnum/fr/__init__.py

@@ -22,5 +22,6 @@
 
 from __future__ import annotations
 
-# provide vat as an alias
+# provide excise and vat as an alias
+from stdnum.fr import accise as excise  # noqa: F401
 from stdnum.fr import tva as vat  # noqa: F401

stdnum/fr/accise.py

@@ -0,0 +1,79 @@
+# accise.py - functions for handling French Accise numbers
+# coding: utf-8
+#
+# Copyright (C) 2023 Cédric Krier
+#
+# 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
+
+"""n° d'accise (French number to identify taxpayers of excise taxes).
+
+The n° d'accise always start by FR0 following by the 2 ending digits of the
+year, 3 number of customs office, one letter for the type and an ordering
+number of 4 digits.
+
+>>> validate('FR023004N9448')
+'FR023004N9448'
+>>> validate('FR0XX907E0820')
+Traceback (most recent call last):
+    ...
+InvalidFormat: ...
+>>> validate('FR012907A0820')
+Traceback (most recent call last):
+    ...
+InvalidComponent: ...
+"""
+
+from __future__ import annotations
+
+from stdnum.exceptions import *
+from stdnum.util import clean, isdigits
+
+
+OPERATORS = set(['E', 'N', 'C', 'B'])
+
+
+def compact(number: str) -> str:
+    """Convert the number to the minimal representation. This strips the number
+    of any valid separators and removes surrounding whitespace."""
+    return clean(number, ' ').upper().strip()
+
+
+def validate(number: str) -> str:
+    """Check if the number is a valid accise number. This checks the length,
+    formatting."""
+    number = compact(number)
+    code = number[:3]
+    if code != 'FR0':
+        raise InvalidFormat()
+    if len(number) != 13:
+        raise InvalidLength()
+    if not isdigits(number[3:5]):
+        raise InvalidFormat()
+    if not isdigits(number[5:8]):
+        raise InvalidFormat()
+    if number[8] not in OPERATORS:
+        raise InvalidComponent()
+    if not isdigits(number[9:12]):
+        raise InvalidFormat()
+    return number
+
+
+def is_valid(number: str) -> bool:
+    """Check if the number is a valid accise number."""
+    try:
+        return bool(validate(number))
+    except ValidationError:
+        return False

tests/test_fr_accise.doctest

@@ -0,0 +1,53 @@
+test_fr_accise.doctest - more detailed doctests for the stdnum.fr.accise module
+
+Copyright (C) 2023 Cédric Krier
+
+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
+
+This file contains more detailed doctests for the stdnum.fr.accise module. It
+tries to validate a number of Excise numbers that have been found online.
+
+>>> from stdnum.fr import accise
+>>> from stdnum.exceptions import *
+
+
+>>> accise.compact('FR0 23 004 N 9448')
+'FR023004N9448'
+>>> accise.validate('FR023004N9448')
+'FR023004N9448'
+>>> accise.validate('FR012907E0820')
+'FR012907E0820'
+
+>>> accise.validate('FR012345')
+Traceback (most recent call last):
+    ...
+InvalidLength: ...
+>>> accise.validate('FR0XX907E0820')
+Traceback (most recent call last):
+    ...
+InvalidFormat: ...
+>>> accise.validate('FR012XXXE0820')
+Traceback (most recent call last):
+    ...
+InvalidFormat: ...
+>>> accise.validate('FR012907A0820')
+Traceback (most recent call last):
+    ...
+InvalidComponent: ...
+>>> accise.validate('FR012907EXXXX')
+Traceback (most recent call last):
+    ...
+InvalidFormat: ...