Use a dict to describe identifier aliases and add a readme

README.md

+# Identity Lib
+
+This Python package contains shared code related to Identity systems within UIS. It's primary
+purpose is to encourage code-reuse and to allow for client systems to make use of the same
+data structures and logic that is contained within our emergent identity APIs.
+
+## Developer quickstart
+
+This project contains a dockerized testing environment which wraps [tox](https://tox.readthedocs.io/en/latest/).
+
+Tests can be run using the `./test.sh` command:
+
+```bash
+# Run all PyTest tests and Flake8 checks
+$ ./test.sh
+
+# Run just PyTest
+$ ./test.sh -e py3
+
+# Run a single test file within PyTest
+$ ./test.sh -e py3 -- tests/test_identifiers.py
+
+# Run a single test file within PyTest with verbose logging
+$ ./test.sh -e py3 -- tests/test_identifiers.py -vvv
+```

identitylib/identifiers.py

-from typing import Optional, List, Callable
+from typing import Optional, List, Callable, Dict
 from collections import namedtuple
 from dataclasses import dataclass
 from functools import lru_cache
@@ -13,7 +13,9 @@ class IdentifierScheme:
 
     identifier: str  # the actual string which identifiers this scheme
     common_name: str  # a common name for this identifier (e.g. CRSid or USN)
-    aliases: List[str]  # a list of equivalent schemes
+    # a dict of aliases - each value being a previous representation of this identifier
+    # keyed on a brief description of that alias
+    aliases: Dict[str, str]
     value_parser: Optional[Callable] = None  # a parser for the value of an id with this scheme
 
     def __str__(self):
@@ -38,44 +40,44 @@ class IdentifierSchemes:
     CRSID = IdentifierScheme(
         'v1.person.identifiers.cam.ac.uk',
         'CRSid',
-        [
-            'person.crs.identifiers.uis.cam.ac.uk',
-            'person.v1.crs.identifiers.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'person.crs.identifiers.uis.cam.ac.uk',
+            'deprecated-versioned': 'person.v1.crs.identifiers.cam.ac.uk',
+        }
     )
 
     USN = IdentifierScheme(
         'person.v1.student-records.university.identifiers.cam.ac.uk',
         'USN',
-        [
-            'person.camsis.identifiers.admin.cam.ac.uk',
-            'person.v1.ust.identifiers.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'person.camsis.identifiers.admin.cam.ac.uk',
+            'deprecated-versioned': 'person.v1.ust.identifiers.cam.ac.uk',
+        }
     )
 
     STAFF_NUMBER = IdentifierScheme(
         'person.v1.human-resources.university.identifiers.cam.ac.uk',
         'Staff Number',
-        [
-            'person.v1.uhr.identifiers.cam.ac.uk',
-            'person.chris.identifiers.admin.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'person.chris.identifiers.admin.cam.ac.uk',
+            'deprecated-versioned': 'person.v1.uhr.identifiers.cam.ac.uk',
+        }
     )
 
     BOARD_OF_GRADUATE_STUDIES = IdentifierScheme(
         'person.v1.board-of-graduate-studies.university.identifiers.cam.ac.uk',
         'Board of Graduate Studies Identifier',
-        [
-            'person.bgs.identifiers.admin.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'person.bgs.identifiers.admin.cam.ac.uk',
+        }
     )
 
     LEGACY_CARDHOLDER = IdentifierScheme(
         'person.v1.legacy-card.university.identifiers.cam.ac.uk',
         'Legacy cardholder Identifier',
-        [
-            'person.bgs.identifiers.admin.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'person.bgs.identifiers.admin.cam.ac.uk',
+        }
     )
 
     """
@@ -86,25 +88,25 @@ class IdentifierSchemes:
     STUDENT_INSTITUTION = IdentifierScheme(
         'institution.v1.student-records.university.identifiers.cam.ac.uk',
         'Student Institution',
-        [
-            'institution.v1.ust.identifiers.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'institution.v1.ust.identifiers.cam.ac.uk',
+        }
     )
 
     HR_INSTITUTION = IdentifierScheme(
         'institution.v1.human-resources.university.identifiers.cam.ac.uk',
         'Human Resources Institution',
-        [
-            'institution.v1.uhr.identifiers.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'institution.v1.uhr.identifiers.cam.ac.uk',
+        }
     )
 
     LEGACY_CARD_INSTITUTION = IdentifierScheme(
         'institution.v1.legacy-card.university.identifiers.cam.ac.uk',
         'Legacy Card Institution',
-        [
-            'inst.legacy_card.identifiers.admin.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'inst.legacy_card.identifiers.admin.cam.ac.uk',
+        }
     )
 
     """
@@ -115,25 +117,25 @@ class IdentifierSchemes:
     STUDENT_ACADEMIC_PLAN = IdentifierScheme(
         'academic-plan.v1.student-records.university.identifiers.cam.ac.uk',
         'Student Academic Plan',
-        [
-            'academicPlan.v1.ust.identifiers.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'academicPlan.v1.ust.identifiers.cam.ac.uk',
+        }
     )
 
     CARD = IdentifierScheme(
         'card.v1.card.university.identifiers.cam.ac.uk',
         'Card Identifier',
-        [
-            'card.card.identifiers.uis.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'card.card.identifiers.uis.cam.ac.uk',
+        }
     )
 
     MIFARE_ID = IdentifierScheme(
         'mifare-identifier.v1.card.university.identifiers.cam.ac.uk',
         'Mifare Identifier',
-        [
-            'mifare_id.card.identifiers.uis.cam.ac.uk'
-        ],
+        {
+            'deprecated': 'mifare_id.card.identifiers.uis.cam.ac.uk',
+        },
         value_parser=(
             lambda v: v.lstrip('0') or '0'  # fallback to '0' to avoid stripping '000' to ''
         )
@@ -142,41 +144,41 @@ class IdentifierSchemes:
     MIFARE_NUMBER = IdentifierScheme(
         'mifare-number.v1.card.university.identifiers.cam.ac.uk',
         'Mifare Number',
-        [
-            'mifare_number.card.identifiers.uis.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'mifare_number.card.identifiers.uis.cam.ac.uk',
+        }
     )
 
     BARCODE = IdentifierScheme(
         'barcode.v1.card.university.identifiers.cam.ac.uk',
         'Card Barcode',
-        [
-            'barcode.identifiers.lib.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'barcode.identifiers.lib.cam.ac.uk',
+        }
     )
 
     CARD_LOGO = IdentifierScheme(
         'card-logo.v1.card.university.identifiers.cam.ac.uk',
         'Card Logo Identifier',
-        [
-            'card_logo.card.identifiers.uis.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'card_logo.card.identifiers.uis.cam.ac.uk',
+        }
     )
 
     PHOTO = IdentifierScheme(
         'photo.v1.photo.university.identifiers.cam.ac.uk',
         'Photo Identifier',
-        [
-            'photo_id.photo.identifiers.uis.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'photo_id.photo.identifiers.uis.cam.ac.uk',
+        }
     )
 
     LEGACY_CARD = IdentifierScheme(
         'card.v1.legacy-card.university.identifiers.cam.ac.uk',
         'Legacy Card Identifier',
-        [
-            'card.legacy_card.identifiers.admin.cam.ac.uk'
-        ]
+        {
+            'deprecated': 'card.legacy_card.identifiers.admin.cam.ac.uk',
+        }
     )
 
     @staticmethod
@@ -203,7 +205,7 @@ class IdentifierSchemes:
         matching_scheme = next((
             scheme for scheme in IdentifierSchemes.get_registered_schemes() if (
                 scheme.identifier == identifier_scheme or
-                find_by_alias and identifier_scheme in scheme.aliases
+                find_by_alias and identifier_scheme in scheme.aliases.values()
             )
         ), None)