feat: adding alpha numeric sequence

Author: quertenmont

.gitattributes

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2013-present Jared Forsyth / Fabio Caccamo
+Copyright (c) 2024-present Loic Quertenmont
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE.txt

@@ -17,6 +17,7 @@
 # sequencefield
 simple model field taking it's value from a postgres sequence.  This is an easy replacement for django autofield offering the following advantages:
 -  Sequence could be shared among multiple models (db tables), so you can now have unique id among multiple django models
+-  Possibility to generate alphanumeric id of the form "{PREFIX}_{ID}"
 -  Unique Id could also be combined with data from other field to build complex id.  One example is given that combine unique id with date information to offer an efficient table indexing/clustering for faster data retrieval when filtering on date.  (Particularly useful with BRIN index)
 
 
@@ -51,6 +52,7 @@ class IntSequenceModel(models.Model):
             IntSequenceConstraint(
                 name="%(app_label)s_%(class)s_custseq",
                 sequence="int_custseq", #name of sequence to use
+                drop=False, #avoid deleting the sequence if shared among multiple tables
                 fields=["id"], #name of the field that should be populated by this sequence
                 start=100, #first value of the sequence
                 maxvalue=200 #max value allowed for the sequence, will raise error if we go above, use None for the maximum allowed value of the db
@@ -59,6 +61,26 @@ class IntSequenceModel(models.Model):
 
 ```
 
+### Simple AlphaNumeric Example
+Just add an AlphaNumericSequenceField field(s) to your models like this.
+You can provide a "format" argument to define how to convert the number to char.  The syntax is the one used in postgres to_char function ([see here](https://www.postgresql.org/docs/current/functions-formatting.html))
+
+class AlphaNumericSequenceModel(models.Model):
+    seqid = AlphaNumericSequenceField(
+        primary_key=False, prefix="INV", format="FM000000"
+    )
+
+    class Meta:
+        constraints = [
+            IntSequenceConstraint(
+                name="%(app_label)s_%(class)s_custseq",
+                sequence="alphanum_custseq", , #name of sequence to use
+                drop=False, #avoid deleting the sequence if shared among multiple tables
+                fields=["seqid"], #name of the field that should be populated by this sequence
+                start=1,
+            )
+        ]
+
 ### Advance Example
 Just add a sequence field(s) to your models like this:
 
@@ -80,12 +102,19 @@ class BigIntSequenceModel(models.Model):
             BigIntSequenceConstraint(
                 name="%(app_label)s_%(class)s_custseq",
                 sequence="gdw_post_custseq", #name of the quence
+                drop=False, #avoid deleting the sequence if shared among multiple tables
                 fields=["seqid"], #field to be populated from this sequence
                 start=1, #first value of the sequence
             )
         ]
 ```
 
+---
+
+## Remarks
+
+Until we find a good solution to properly handle supression of a sequence shared among multiple tables,
+It's better to pass the flag drop=False in the SequenceConstraint.  Otherwise a sequence that is still being used by another table might be deleted.
 
 ---
 

README.md

@@ -6,14 +6,17 @@
 class SequenceConstraint(BaseConstraint):
     maxvalue: int | None = None
 
-    def __init__(self, name=None, sequence="", maxvalue=None, fields=(), start=1):
+    def __init__(
+        self, name=None, sequence="", drop=True, maxvalue=None, fields=(), start=1
+    ):
         if not sequence:
             raise TypeError(
                 f"{self.__class__.__name__}.__init__() missing 1 required keyword-only "
                 f"argument: 'sequence'"
             )
 
         self.fields = tuple(fields)
+        self.drop = drop
         self.start = start
         self.sequence = sequence
         self.maxvalue = maxvalue if maxvalue else self.maxvalue
@@ -25,6 +28,7 @@ def __eq__(self, other):
             return (
                 self.name == other.name
                 and self.fields == other.fields
+                and self.drop == other.drop
                 and self.sequence == other.sequence
                 and self.maxvalue == other.maxvalue
             )
@@ -33,6 +37,7 @@ def __eq__(self, other):
     def deconstruct(self):
         path, args, kwargs = super().deconstruct()
         kwargs["sequence"] = self.sequence
+        kwargs["drop"] = self.drop
         kwargs["fields"] = self.fields
         kwargs["start"] = self.start
         kwargs["maxvalue"] = self.maxvalue
@@ -68,10 +73,13 @@ def remove_sql(self, model, schema_editor):
         assert schema_editor
         assert model
 
-        return schema_editor.execute(
-            sql=f"""DROP SEQUENCE IF EXISTS {self.sequence}""",
-            params=(),
-        )
+        if self.drop:
+            return schema_editor.execute(
+                sql=f"""DROP SEQUENCE IF EXISTS {self.sequence}""",
+                params=(),
+            )
+
+        return
 
     def validate(self, model, instance, exclude=None, using=DEFAULT_DB_ALIAS):
         print("CALL VALIDATE")

sequencefield/constraints.py

@@ -3,12 +3,20 @@
 
 from django.core import checks
 from django.db import models
-from django.db.models import BigIntegerField, Field, IntegerField, SmallIntegerField
+from django.db.models import (
+    BigIntegerField,
+    CharField,
+    Field,
+    IntegerField,
+    SmallIntegerField,
+    Value,
+)
 from django.db.models.expressions import Expression
+from django.db.models.functions import Cast, Concat
 from django.utils.functional import cached_property
 
 from .constraints import SequenceConstraint
-from .functions import LeftShift, NextSeqVal
+from .functions import LeftShift, NextSeqVal, ToChar
 
 
 class SequenceFieldMixin(Field):
@@ -73,6 +81,36 @@ class BigIntegerSequenceField(SequenceFieldMixin, BigIntegerField):
     pass
 
 
+class AlphaNumericSequenceField(SequenceFieldMixin, CharField):
+    def __init__(self, *args, prefix, separator="_", format: str = "", **kwargs):
+        super().__init__(*args, **kwargs)
+        self.prefix = prefix
+        self.separator = separator
+        self.format = format
+
+    # needed to store the additional parameter
+    def deconstruct(self):
+        name, path, args, kwargs = super().deconstruct()
+        if self.prefix:
+            kwargs["prefix"] = self.prefix
+        if self.separator:
+            kwargs["separator"] = self.separator
+        if self.format:
+            kwargs["format"] = self.format
+        return name, path, args, kwargs
+
+    def get_db_expression(self, model_instance) -> Expression:
+        seqid = super().get_db_expression(model_instance)
+        if self.format:
+            seqid = ToChar(seqid, format=self.format)
+        else:
+            seqid = Cast(seqid, output_field=CharField())
+
+        return Concat(
+            Value(self.prefix + self.separator), seqid, output_field=CharField()
+        )
+
+
 class BigIntegerWithDateSequenceField(SequenceFieldMixin, BigIntegerField):
     def __init__(self, *args, datetime_field, **kwargs):
         super().__init__(*args, **kwargs)

sequencefield/fields.py

@@ -1,4 +1,4 @@
-from django.db.models import DateField
+from django.db.models import CharField, DateField
 from django.db.models.expressions import Func
 
 
@@ -11,6 +11,17 @@ def __init__(self, sequence="", output_field=None):
         super().__init__(output_field=output_field, template=template)
 
 
+class ToChar(Func):
+    template = ""
+    arity = 1
+
+    def __init__(self, *expressions, format="", output_field=None):
+        template = f"to_char(%(expressions)s, '{format}')"
+        super().__init__(
+            *expressions, output_field=output_field or CharField(), template=template
+        )
+
+
 class LeftShift(Func):
     template = ""
     arity = 1

sequencefield/functions.py

@@ -10,4 +10,4 @@
 __email__ = "[email protected]"
 __license__ = "MIT"
 __title__ = "django-sequencefield"
-__version__ = "1.0.6"
+__version__ = "1.0.7"

sequencefield/metadata.py

@@ -2,6 +2,7 @@
 
 from sequencefield.constraints import BigIntSequenceConstraint, IntSequenceConstraint
 from sequencefield.fields import (
+    AlphaNumericSequenceField,
     BigIntegerWithDateSequenceField,
     IntegerSequenceField,
 )
@@ -42,6 +43,42 @@ def __str__(self) -> str:
         return f"seqid:{self.seqid}"
 
 
+class AlphaNumericSequenceModelA(models.Model):
+    seqid = AlphaNumericSequenceField(primary_key=True, prefix="INV")  # type: ignore
+
+    class Meta:
+        constraints = [
+            IntSequenceConstraint(
+                name="%(app_label)s_%(class)s_custseq",
+                sequence="alphanumA_custseq",
+                fields=["seqid"],
+                start=1,
+            )
+        ]
+
+    def __str__(self) -> str:
+        return f"seqid:{self.seqid}"
+
+
+class AlphaNumericSequenceModelB(models.Model):
+    seqid = AlphaNumericSequenceField(
+        primary_key=False, prefix="INV", format="FM000000"
+    )  # type: ignore
+
+    class Meta:
+        constraints = [
+            IntSequenceConstraint(
+                name="%(app_label)s_%(class)s_custseq",
+                sequence="alphanumB_custseq",
+                fields=["seqid"],
+                start=1,
+            )
+        ]
+
+    def __str__(self) -> str:
+        return f"seqid:{self.seqid}"
+
+
 class BigIntSequenceModel(models.Model):
     id = models.BigIntegerField(primary_key=True, auto_created=False)
     seqid = BigIntegerWithDateSequenceField(datetime_field="created")  # type: ignore

tests/models.py

@@ -5,13 +5,15 @@
 
 from sequencefield.functions import DateFromId, RightShift
 from tests.models import (
+    AlphaNumericSequenceModelA,
+    AlphaNumericSequenceModelB,
     BigIntSequenceModel,
     IntSequenceModelA,
     IntSequenceModelB,
 )
 
 
-class ColorFieldTestCase(TestCase):
+class SequenceFieldTestCase(TestCase):
     def setUp(self):
         pass
 
@@ -36,6 +38,22 @@ def test_model_id(self):
         a2.save()
         self.assertEqual(a2.seqid, 102)
 
+    def test_model_alphanumeric_wfmt(self):
+        """
+        Checking that alphanumeric model works fine
+        """
+        b = AlphaNumericSequenceModelB()
+        b.save()
+        self.assertEqual(b.seqid, "INV_000001")
+
+    def test_model_alphanumeric_wofmt(self):
+        """
+        Checking that alphanumeric model works fine
+        """
+        a = AlphaNumericSequenceModelA()
+        a.save()
+        self.assertEqual(a.seqid, "INV_1")
+
     def test_model_idWithDate(self):
         """
         Checking that id we can generate an id containing a data value inside
@@ -49,9 +67,10 @@ def test_model_idWithDate(self):
         data = BigIntSequenceModel.objects.values(
             epochdays=RightShift("seqid", bits=48)
         ).first()
-        print("epochdays", data)
+        assert data
         self.assertEqual(data["epochdays"], math.floor(dt.timestamp() / 86400))
 
         # verify that we can extract the date from the id itself
         data = BigIntSequenceModel.objects.values(date=DateFromId("seqid")).first()
+        assert data
         self.assertEqual(data["date"], dt.date())