Add a decorator to escapsulate admin method properties

[Jaap Roes]

While doing some heavy admin customisation I got fed up repeating function names to add short_description, admin_order_field (etc.) to helpers used in list_display. So I created a decorator that does it for me. It has the added benefit of enabling autocompletion on the possible options for list_display methods in PyCharm.

def list_display_method(short_description=None, allow_tags=False, boolean=False, admin_order_field=None):
    """
    Convenient decorator for display functions used in admin list_display.
    """
    def inner(func):
        func.short_description = short_description or func.__name__
        func.allow_tags = allow_tags
        func.boolean = boolean
        func.admin_order_field = admin_order_field
        return func
    return inner

Used like this:

@list_display_method(_('Some description'), admin_order_field='other_field')
def show_other_field(obj):
     return obj.other_field

Would something like this be eligible for inclusion in contrib.admin?

[Tim Graham]

Sounds reasonable to me. Maybe a more generic name like @admin_method() would be better since these items can be used on more than just the changelist page? I think we could also drop the admin_ prefix on order_field in the decorator's signature too.

If we're able to deprecate allow_tags in #25135, then we should omit that here.

[Jaap Roes]

Maybe @display_method? @admin_method feels a bit too generic to me.

Having looked at the code in admin_list.items_for_result it seems that exposing row_classes and empty_value_display would be useful as well.

[Tim Graham]

I'm not enthusiastic about putting more admin attributes in models.py. While it might not be worthwhile to deprecate the existing customization that can be done there, I think any further customization should live in ModelAdmin. For that reason, we might consider closing this ticket as "won't fix" as such a decorator would add a dependency in models.py on contrib.admin (I presume the decorator would live in there).

[Jaap Roes]

Not sure if I follow you. In the case of list_display it can be a standalone function, a method on the ModelAdmin or an attribute of the model. ​https://docs.djangoproject.com/en/1.8/ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_display

The same goes for readonly_fields except that it can't be a callable directly (is that right?) ​https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.ModelAdmin.readonly_fields

I personally prefer creating these display methods on the applicable admin class. That's where I've used this decorator and would use this decorator.

I guess there's nothing to stop people from using it in models.py. To discourage people from using this in models the docs could maybe deemphasise the models.py use cases? Most of the examples could be rewritten to a standalone function or a method on the ModelAdmin.

[Tim Graham]

Okay, sorry I forgot about that use case. That seems fine. I would make an initial implementation using the existing attributes as options, then we can talk about exposing the other attributes you mentioned.

[Tim Graham]

Duplicate of #16117

[GitHub <noreply@…>]

In 9204485:

Fixed #16117 -- Added decorators for admin action and display functions.

Refs #25134, #32099.