From 1099250ca5a374ed3c65c1f687d117e109702b96 Mon Sep 17 00:00:00 2001 From: Pelagic Date: Tue, 12 Sep 2023 13:35:47 +0300 Subject: [PATCH] Wrote the Usage section in README.md --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/README.md b/README.md index bc9583e..1a8aa50 100644 --- a/README.md +++ b/README.md @@ -4,3 +4,64 @@ This repository holds the django library that StarFields uses for the django-res It changes the generic lifecycles of all the CRUD operations to fit within them automated caching functionality. Caching and deleting cache keys is handled by the library in a way that the cache keys have no duplicates. The generic views offered include single item CRUD and list-based CRUD. To manage automated caching this the library replaces (and appends to) the DRF filters. These filters need a get_unique_dict method in order to avoid the duplicate cache keys problem. + +# Usage +##### Ensure that the module is in the INSTALLED_APPS in settings.py: +INSTALLED_APPS = [ + ... + 'starfields_drf_generics', +] + +##### Making views in views.py: +from starfields_drf_generics import generics +from starfields_drf_generics import filters as libfilters + +class CategoriesView(generics.CachedListRetrieveAPIView): + """ + This view lists all the categories. Usually this API is called on the shop initialization and the result is saved on the front-end for use shop-wide. + """ + cache_prefix = "shop.products.categories" + cache_vary_on_user = False + cache_timeout_mins = ShopSettings.get_solo().cache_timeout + queryset = Category.objects.all() + serializer_class = CategorySerializer + paged = False + filter_backends = [] + logger = logger + cache = cache + +class SearchView(generics.CachedListRetrieveAPIView): + """ + This view lists the gallery pictures with extensive searching and filtering features. You can use this API to get the latest pictures, perform picture searches among others. + """ + cache_prefix = "gallery.search" + cache_vary_on_user = False + cache_timeout_mins = GallerySettings.get_solo().cache_timeout + queryset = Picture.objects.filter(published=True) + serializer_class = PictureSerializer + ordering_fields = ('similarity','date_added','updated') + category_class = Category + search_fields = ['name','slug','tag__name','tag__slug'] + paged = True + default_page_size = 20 + filter_backends = (libfilters.CategoryFilter, + libfilters.TrigramSearchFilter, + libfilters.OrderingFilter, + ) + logger = logger + cache = cache + +### New class attributes that are used +cache_prefix: defines the prefix that the module will use when saving values in the cache +cache_vary_on_user: defines whether keys saved in the cache are different for each user, in which case extra user information will be added to the cache prefix +cache_timeout_mins: the cache key timeout +filter_backends: the filters that you want the view to have, each can be configured with view class attributes +ordering_fields: if you use the OrderingFilter you must indicate what fields the user can order by, the first element is used as the default order +search_fields: if you use the TrigramSearchFilter you must indicate the fields to search through +paged: your generic view can have a pager for the user to choose pages or it can be a full listing +default_page_size: the default size of the pages if a user has not indicated a page size +logger: you should register a logger in order to get error feedback in your deployments +cache: the main feature of this module is automated and organized caching, you should register your cache here + +### Extras +The source code is similar to the django-rest-framework's generic classes and related objects, it should be eminently readable. A new method is added in each filter named get_unique_dict that aids in fixing the duplicate key problem.