Package: django-building-blocks
Django Building BlocksAbstract Django base models (and model class factories) to act as building blocks for rapid development of Django
database modelsQuick startpipinstalldjango-building-blocksRationaledjango-building-blocksprovides common design patterns and behaviours that repeat themselves during the development of
django projects. The main aim of this package is to provide common interfaces for the development of django models. This
portion of this library is inspired by Kevin Stone's excellent blog
postDjango Model Behaviors. The secondary aim of this library is
to provide interfaces and mixins for Django admin classes, so you can add functionality to your admin pages really fast,
without the need to Google solutions and look at Stackoverflow for answers.By using this library you can create models in such a way to make their fields standard across your entire project and
all your projects. For example:classBlogPost(HasNameFactory.as_abstract_model(),HasDescription,HasHTMLBody,Publishable,models.Model):passNote that we did not need to add anything to the body of the above model. This model is entirely composed of abstract
models (and abstract model factories - more on this later). If you have another model:classWebPage(HasNameFactory.as_abstract_model(),HasAutoSlugFactory.as_abstract_model(),HasHTMLBody,Publishable,models.Model):passNote the similarity between the two models. Now instead of having to code the fields, associated properties and
behaviors on each model individually, you can reuse them infinite times, and keep them standard across your project (and
all your projects).The admin class forBlogPostwould look something like this:@admin.register(BlogPost)classBlogPostAdmin(PublishableAdmin,admin.ModelAdmin):list_display=(*HasNameAdmin.list_display,*PublishableAdmin.list_display,...)...Notice how we have composed each element in the admin using a concept called Admin Blocks. Each of the abstract classes
in this library, have an associated Admin block class (which looks like a normal admin class, but usually isn't meant to
be inherited), that enables you to define admin for their inheritors in a standard way. For example in the case
ofPublishable, you would probably like to show the publication status and date inlist_display. Instead of having
to remember to include both fields in all your admins, you can just include the Admin block in the way showed above and
have the fields show up in the list table for all the inheritors ofPublishable.Details and classes providedNote: Check the docstring under each class for their documentation.Abstract modelsDjango Model Behaviorsdescribes a design pattern for developing
django models that makes them compositional. For example, your project might have the ability to post blog
posts (BlogPost), and each post goes through 3 stages: Draft, Published, and Archived. In your project, your users
might also have the ability to post shorter status updates (StatusUpdate), and you'd like those status updates to also
go through a similar publishing pipeline. Furthermore, bothBlogPostandStatusUpdateare timestamped with the date
and time they are published.As a seasoned developer, instead of coding the functionality on both models, you would create an abstract model, let's
call itPublishable, and have bothBlogPostandStatusUpdateinherit from it. Now you have abstracted away common
functionality between your models, into thePublishableinterface/abstract model. Not only this is DRY, but also if
you like to make updates to how your publishing pipeline works, you can just updatePublishableand bothBlogPostandStatusUpdatewould get updated with the new pipeline.django-building-blocksprovides a number of such abstract models:HasUUIDArchivablePublishableNote: if you're coming from v0.0.x, take a look at thismigration fileto help you with writing migrations for yourArchivableorPublishablemodels, as in v0.1.0 they have switched to
use an integer status field.Abstract model factoriesAbstract model factories enable you to create abstract models on the fly. Abstract model factories enable you to modify
the inherited fields dynamically from the same base class. For example, you might have a model that will have anemailfield. You can useHasEmailFactory.as_abstract_model()that returns an abstract model that can be inherited from. Now
say you have another model that also has a email, but the email here is an optional field (blank=True). Instead of
creating a whole new abstract model (likeHasOptionalEmail), you can inherit
fromHasEmailFactory.as_abstract_model(optional=True)which will return an abstract model with the sameemailfield,
but this time theemailfield is optional.Abstract model factories provided:HasNameFactoryHasEmailFactoryHasDescriptionFactoryHasCoverPhotoFactoryHasIconFactoryHasUserFactoryHasAutoCodeFactoryHasAutoSlugFactoryYou can create your own abstract model factory by inheriting
frombuilding_blocks.models.factories.AbstractModelFactory. Check some of the implementations for an example.Mixin model classesHasInitialsHasAutoFieldsAdmin block classesThe following admins (called admin blocks) aren't usually meant to be inherited by your model's admin class. Instead,
each field in the admin is used to create your desired admin class. For example:# example/sample/admin.py@admin.register(ArchivableHasUUID)classArchivableHasUUIDAdmin(ArchivableAdmin,# Inheritable admin to add common functionality. More on this later.admin.ModelAdmin):search_fields=(*HasUUIDAdmin.search_fields,# AdminBlock to assist in shaping the admin)list_display=(*HasUUIDAdmin.list_display,*ArchivableAdmin.list_display,)list_filter=(*ArchivableAdmin.list_filter,)readonly_fields=(*HasUUIDAdmin.readonly_fields,*ArchivableAdmin.readonly_fields,)fieldsets=(*HasUUIDAdmin.fieldsets,*ArchivableAdmin.fieldsets,)As its name suggests, the modelArchivableHasUUIDinherits from bothArchivableandHasUUIDand thus has fields
form both. With admin blocks you can createArchivableHasUUIDAdminwithout mentioning individual fields from each
class, adding to the conciseness of your code. It'll also make it hard to miss a field since the AdminBlock has the
default and recommended fields for each admin field.Available Admin Blocks:HasUUIDAdminArchivableAdminPublishableAdminHasInitialsAdminHasNameAdminHasEmailAdminHasDescriptionAdminHasCoverPhotoAdminHasIconAdminHasUserAdminHasAutoSlugAdminTimeStampedModelAdminInheritable Admin block classesSome Admin block classes are also meant to be inherited by your admin class. The usually provide functionality such as
common admin actions to your admin.ArchivableAdminPublishableAdminPlease note that the majority of the inheritable admins
usedjango-object-actionsto enable admin actions on objects'admin:changepages. To enable this functionality add'django_object_actions'to yourINSTALLED_APPSso your
project can find the templates fromdjango_object_actionswhich are used in rendering the buttons for the actions.Mixin Admin classesEditReadonlyAdminMixinPrepopulateSlugAdminMixinDjangoObjectActionsPermissionsMixinAreYouSureActionsAdminMixinAdmin inline mixinsWhen you need some fields on an inline admin to be readonly only for editing (equivalent ofEditReadonlyAdminMixin),
you have to split the interface into two inlines, one for adding which doesn't show any objects, and one for listing
them, which has the readonly fields defined. The following classes facilitate this design pattern:AddInlineMixinListInlineMixinReadOnlyInlineMixinHTML render utilitiesThey are used in conjunction with@admin.displayto render html such as anchor tags, or images on the admin.json_field_pprender_elementrender_imgrender_anchorFormsUnrequiredFieldsFormandunrequire_formMake fields that are usually required in a model form, be not required. Used in conjunction withHasAutoFields, since
the fields that aren't required are auto set. Also used in conjunction withEditReadonlyAdminMixinto allow manual
setting of a field upon creation.FieldsCaseInsensitiveFieldMixinToLowerCaseFieldMixinLowerCaseCharFieldDevelopment and TestingIDE SetupAdd theexampledirectory to thePYTHONPATHin your IDE to avoid seeing import warnings in thetestsmodules. If
you are using PyCharm, this is already set up.Running the TestsInstall requirementspip install -r requirements.txtFor local environmentpytestFor all supported environmentstox