Package: django-spicy-id
django-spicy-idA drop-in replacement for Django'sAutoFieldthat gives you "Stripe-style" self-identifying string object IDs, likeuser_1234.Status:Stable. No warranty, seeLICENSE.txt.Table of ContentsWhat is a "spicy" id?Why use spicy ids?InstallationRequirementsInstructionsUsageField typesRequired ParametersOptional ParametersRegistering URLsDjango REST FrameworkField Attributes.validate_string(strval).re.re_patternUtility methodsget_url_converter(model_class, field_name)Errorsdjango.db.utils.ProgrammingErrordjango_spicy_id.MalformedSpicyIdErrorTips and tricksDon't change field configurationChangelogWhat is a "spicy" id?It's a made-up name (because I couldn't think of a better one) for a numeric primary keys type that is shown and manipulated as a string, prefixed with a constant value.Here are some examples. You can use this library to make your Django row IDs look like:user_1234account-00000000deadbeefbloop:1a2k3841xAlthough you should always treat these values as opaque andneverdecode or parse the string's contents elsewhere (seeErrors), you can think of every spicy id as being composed of:<prefix> <separator> <encoded_value>prefix: A fixed string value that will be the same for all IDs of this record type, forever.separator: A configurable separator which, likeprefix, is fixed forever; usually_(the default) or-(another popular choice).encoded_value: The numeric portion of the id. This library supports using base 16 (hex) or base 62.Importantly, the underlying database value is still stored and retrieved as anumeric type, just like anAutoField,SmallAutoField, orBigAutoField.Why use spicy ids?Briefly: Because they're so much nicer for humans to work with.Readability:While row-level primary keys are typically treated as "anonymous" (as in "not something anyone should have to care about"), the fact is these values stillshow upin lots of situations: They're in URLs, dumped in logfiles, shown in queries, and so on. In these situations, it's just plain faster to understand "what am I looking at" when the identifier itself tells you its type.Conflict and accident prevention:When your systems require you to pass around typed identifiers likeacct_1234andinvoice_5432beef, certain kinds of accidents become impossible. For example,HTTP DELETE /users/invoice_21fails fast.Future-proofing:Adopting spicy IDs means your systems and APIs are developed to accept a basically-opaque string as an ID. While their underlying type is numeric, in very advanced situations you may be able to migrate to a different type or datastore "behind" the abstraction the string ID creates.For a more detailed look at this pattern, see Stripe's"Object IDs: Designing APIs for Humans".InstallationRequirementsThis package supports and is tested against the latest patch versions of:Python:3.9, 3.10, 3.11, 3.12Django:3.2, 4.2MySQL:5.7, 8.0PostgreSQL:9.5, 10, 11, 12SQLite:3.9.0+All database backends are tested with the latest versions of their drivers. SQLite is also tested on GitHub Actions' latest macOS virtual environment.Note:Django 4.x is recommended due to anupstream bugthat is present in 3.x. See#6for further details.Instructionspip install django_spicy_idUsageGiven the following example model:fromdjango.dbimportmodelsfromdjango_spicy_idimportSpicyBigAutoFieldclassUser(models.model):id=SpicyBigAutoField(primary_key=True,prefix='usr')Example usage:>>>u=models.User.objects.create()>>>u.id'usr_1'>>>u2=models.User.objects.create(id=123456789)>>>u2.id'usr_8M0kX'>>>found_user=models.User.objects.filter(id='usr_8M0kX').first()>>>found_user==u2TrueField typesSpicyBigAutoField: A spicy id which is backed by aBigAutoField(i.e. 64-bit int) column.SpicyAutoField: A spicy id which is backed by aAutoField(i.e. 32-bit int) column.SpicySmallAutoField: A spicy id which is backed by aSmallAutoField(i.e. 16-bit int) column.Required ParametersThe following parameters are required at declaration:prefix: The prefix to use in the encoded form. Typically this is a short, descriptive string, likeuseroracctand similar.Note:This library does not ensure the string you provide is unique within your project. You should ensure that.Optional ParametersIn addition to all parameters you can provide a normalAutoField, each of the field types above supports the following additional optional paramters:encoding: What numeric encoding scheme to use. One ofdjango_spicy_id.ENCODING_BASE_62(default),django_spicy_id.ENCODING_BASE_58, ordjango_spicy_id.ENCODING_HEX.sep: The separator character. Defaults to_. Can be any string.pad: Whether the encoded portion of the id should be zero-padded so that all values are the same string length. EitherFalse(default) orTrue.Example without padding:user_8M0kXExample with padding:user_0000008M0kXrandomize: IfTrue, the default value of a new record will be generated randomly usingsecrets.randbelow(). IfFalse(the default), works just like a normalAutoFieldi.e. the default value comes from the database uponINSERT.Whenrandomizeis set, an error will be thrown ifdefaultis also set, sincerandomizeis essentially a special and built-indefaultfunction.Sincerandomizeinstalls a specialdefaultfunction, a new but unsaved model instance will have a non-Nonevalue forobject.id/object.pk. You must usedobject._state.addingto determine whether an instance is a new but unsaved object.If you use this feature, be aware of its hazards:The generated ID may conflict with an existing row, with probabilitydetermined by the birthday problem(i.e. the column size and the size of the existing dataset).A conflict can also arise if two processes generate the same value forsecrets.randbelow()(i.e. if system entropy is identical or misconfigured for some reason).Registering URLsWhen installing routes that must match a specific spicy id, you can use theget_url_converter()helper method to install a Djangocustom path converter.Using this method will ensure thatonlyvalid spicy ID strings for that field will be presented to your view.Example:# models.pyclassUser(models.model):id=SpicyBigAutoField(primary_key=True,prefix='usr')# urls.pyfrom.importmodelsfromdjango.urlsimportpath,register_converterfromdjango_spicy_idimportget_url_converter# Register the pattern for `User.id` as "spicy_user_id". You should do this# once for each unique spicy ID field.register_converter(get_url_converter(models.User,'id'),'spicy_user_id')urlpatterns=[path('users/<spicy_user_id:id>',views.user_detail),...]# views.pydefuser_detail(request,id):user=models.User.objects.get(id=id)...Django REST FrameworkDjango REST Framework (DRF) works mostly without issue withdjango-spicy-id. However, an additional step is needed so that DRF treats spicy ID fields as strings, not integers, in serializers.You can use the included utility function to monkey patch DRF. It is safe to call this method multiple times.fromdjango_spicy_idimportmonkey_patch_drfmonkey_patch_drf()Field AttributesThe following attributes are available on the field once constructed.validate_string(strval)Checks whetherstrvalis a legal value for the field, throwingdjango_spicy_id.errors.MalformedSpicyIdErrorif not..reA compiled regex which can be used to validate a string..re_patternA string regex pattern which can be used to validate a string. Unlike the pattern used inre, this pattern does not include the leading^and trailing$boundary characters, making it easier to use in things like Django url patterns.You probably don't need to use this directly, instead seeget_url_converter().Utility methodsThese utility methods are provided on the top-leveldjango_spicy_idmodule.get_url_converter(model_class, field_name)Returns a Djangocustom path converterforfield_nameonmodel_class.SeeRegistering URLsfor example usage.Errorsdjango.db.utils.ProgrammingErrorThrown when attempting to access or query this field using an illegal value. Some examples of this situation:Providing a spicy id with the wrong prefix or separator (e.gid="acct_1234"whereid="invoice_1234"is expected).Providing a string with illegal characters in it (i.e. where the encoded part isn't decodable)Providing an unpadded value when padding is enabled.Providing a padded value when padded is disabled.You can consider these situations analogous to providing a wrongly-typed object to any other field type, for exampleSomeModel.objects.filter(id=object()).You can avoid this situation by validating inputs first. SeeField Attributes.🚨 Warning:Regardless of field configuration, the string value of a spicy id mustalwaysbe treated as anexact value. Just like you would never modify the contents of aUUID4, a spicy id string must never be translated, re-interpreted, or changed by a client.django_spicy_id.MalformedSpicyIdErrorA subclass ofValueError, raised by.validate_string(strval)when the provided string is invalid for the field's configuration.Tips and tricksDon't change field configurationChangingprefix,sep,pad, orencodingafter you have started using the field should be considered abreaking changefor any external callers.Although the stored row IDs are never changed, any spicy IDs generated previously, with a different encoding configuration, may now be invalid or (potentially catastrophically) resolve to a different object.For just one example,user_10would naturally refer to a different numeric row id if parsed ashexversusbase62orbase58. You should avoid changing the field configuration.ChangelogSeeCHANGELOG.mdfor a summary of changes.