Awl Documentation. Release Christopher Trudeau

Transcription

1 Awl Documentation Release Christopher Trudeau Jan 09, 2018

2

3 Contents 1 Installation 3 2 Supports 5 3 Docs & Source 7 4 Contents Admin Tools Context Processors CSS Colours View Decorators Abstract Models Models RankedModel RankedModel Admin Template Tags & Filters Utilities Waelsteng Indices and tables 23 Python Module Index 25 i

4 ii

5 Yet another catch-all of tools for django. Includes utilities for admin, context processors, CSS colours, view and model mixins, template tags and unit testing. Contents 1

6 2 Contents

7 CHAPTER 1 Installation $ pip install django-awl 3

8 4 Chapter 1. Installation

9 CHAPTER 2 Supports django-awl has been tested with Python 2.7, 3.5, 3.6 and Django 1.11 and

10 6 Chapter 2. Supports

11 CHAPTER 3 Docs & Source Docs: Source: Version:

12 8 Chapter 3. Docs & Source

13 CHAPTER 4 Contents 4.1 Admin Tools A collection of utilites for writing better django admin objects. awl.admintools.admin_obj_attr(obj, attr) A safe version of :func:utils.get_obj_attr that returns and empty string in the case of an exception or an empty object awl.admintools.admin_obj_link(obj, display= ) Returns a link to the django admin change list with a filter set to only the object given. Parameters obj Object to create the admin change list display link for display Text to display in the link. Defaults to string call of the object Returns Text containing HTML for a link awl.admintools.make_admin_obj_mixin(name) This method dynamically creates a mixin to be used with your ModelAdmin classes. The mixin provides utility methods that can be referenced in side of the admin object s list_display and other similar attributes. Parameters name Each usage of the mixin must be given a unique name for the mixin class being created Returns Dynamically created mixin class The created class supports the following methods: add_obj_ref(funcname, attr, [title, display]) Django admin list_display does not support the double underscore semantics of object references. This method adds a function to the mixin that returns the str(obj) value from object relations. Parameters 9

14 funcname Name of the function to be added to the mixin. In the admin class object that includes the mixin, this name is used in the list_display tuple. attr Name of the attribute to dereference from the corresponding object, i.e. what will be dereferenced. This name supports double underscore object link referencing for models. ForeignKey members. title Title for the column of the django admin table. If not given it defaults to a capitalized version of attr display What to display as the text in the column. If not given it defaults to the string representation of the object for the row: str(obj). This parameter supports django templating, the context for which contains a dictionary key named obj with the value being the object for the row. add_obj_link(funcname, attr, [title, display]) This method adds a function to the mixin that returns a link to a django admin change list page for the member attribute of the object being displayed. Parameters Example usage: funcname Name of the function to be added to the mixin. In the admin class object that includes the mixin, this name is used in the list_display tuple. attr Name of the attribute to dereference from the corresponding object, i.e. what will be lined to. This name supports double underscore object link referencing for models. ForeignKey members. title Title for the column of the django admin table. If not given it defaults to a capitalized version of attr display What to display as the text for the link being shown. If not given it defaults to the string representation of the object for the row: str(obj). This parameter supports django templating, the context for which contains a dictionary key named obj with the value being the object for the row. # ---- models.py file ---- class Author(models.Model): name = models.charfield(max_length=100) class Book(models.Model): title = models.charfield(max_length=100) author = models.foreignkey(author, on_delete=models.cascade) # ---- admin.py file class Author(admin.ModelAdmin): list_display = ('name', ) mixin = make_admin_obj_mixin('bookmixin') mixin.add_obj_link('show_author', 'Author', 'Our Authors', '{{obj.name}} 10 Chapter 4. Contents

15 class BookAdmin(admin.ModelAdmin, mixin): list_display = ('name', 'show_author') A sample django admin page for Book would have the table: Name Hitchhikers Guide To The Galaxy War and Peace Dirk Gently Our Authors Douglas Adams (id=1) Tolstoy (id=2) Douglas Adams (id=1) Each of the items in the Our Authors column would be a link to the django admin change list for the Author object with a filter set to show just the object that was clicked. For example, if you clicked Douglas Adams (id=1) you would be taken to the Author change list page filtered just for Douglas Adams books. The add_obj_ref method is similar to the above, but instead of showing links, it just shows text and so can be used for view-only attributes of dereferenced objects. 4.2 Context Processors awl.context_processors.extra_context(request) Adds useful global items to the context for use in templates. request: the request object HOST: host name of server IN_ADMIN: True if you are in the django admin area 4.3 CSS Colours This module defines helpers for dealing with CSS colour strings. The following constants are available: PREDEFINED: Tuple of the predefined colour literals available in most web browsers HEX_MATCH [Compiled regular expression for HEX CSS colour values such as] #F1A or #AB4CD9 RGB_MATCH [Compiled regular expression for rgb function calls such as] rgb(0, 12, 255) RGBA_MATCH: Compiled regular expression for rgba function calls such as rgba(0, 12, 255, 0.3) HSL_MATCH: Compiled regular expression for hsl function calls such as hsl(120, 5%, 200%) HSLA_MATCH: Compiled regular expression for hsla function calls such as hsla(120, 5%, 200%, 0.3) awl.css_colours.is_colour(value) Returns True if the value given is a valid CSS colour, i.e. matches one of the regular expressions in the module or is in the list of predetefined values by the browser. 4.4 View Decorators awl.decorators.post_required(method_or_options=[]) View decorator that enforces that the method was called using POST. This decorator can be called with or 4.2. Context Processors 11

16 without parameters. As it is expected to wrap a view, the first argument of the method being wrapped is expected to be a request def some_view(request): 'lastname']) def some_view(request): pass The optional parameter contains a single list which specifies the names of the expected fields in the POST dictionary. The list is not exclusive, you can pass in fields that are not checked by the decorator. Parameters options List of the names of expected POST keys. 4.5 Abstract Models This is a collection of abstract django models that can be used as base classes or mixins with your regular django models. class awl.absmodels.timetrackmodel(*args, **kwargs) Abstract model with auto-updating create & update timestamp fields. Parameters created Date/time when the model was created updated Date/time when the model was last updated class awl.absmodels.validatingmixin(*args, **kwargs) Include this mixin to force model validation to happen on each save call. 4.6 Models This is a collection of django models base models that can be helpful in your implementations. class awl.models.choices A tuple of tuples pattern of ((id1, string1), (id2, string2)... ) is common in django for choices fields, etc. This object inspects its own members (i.e. the inheritors) and produces the corresponding tuples. class Colours(Choices): RED = 'r' LIGHT_BLUE = 'b' >> Colours.RED 'r' >> list(colours) [('r', 'Red'), ('b', 'Light Blue')] A member value can also be a tuple to override the default string class Colours(Choices): RED = 'r' BLUE = 'b', 'Blueish' 12 Chapter 4. Contents

17 >> list(colours) [('r', 'Red'), ('b', 'Blueish')] A inheriting class can also add or override members. class Colours(Choices): RED = 'r' BLUE = 'b' class MoreColours(Colours): GREEN = 'g' BLUE = 'b', 'Even More Blue' >> list(colours) [('r', 'Red'), ('b', 'Even More Blue'), ('g', 'Green')] class awl.models.counter(*args, **kwargs) A named counter in the database with atomic update. classmethod increment(name) Call this method to increment the named counter. This is atomic on the database. Parameters name Name for a previously created Counter object class awl.models.lock(*args, **kwargs) Implements a simple global locking mechanism across database accessors by using the select_for_update() feature. Example: # run once, or use a fixture Lock.objects.create(name='everything') # views.py def something(request): Lock.lock_until_commit('everything') classmethod lock_until_commit(name) Grabs this lock and holds it (using select_for_update()) until the next commit is done. Parameters name Name for a previously created Lock object class awl.models.querysetchain(*subquerysets) Chains together multiple querysets (possibly of different models) and behaves as one queryset. Supports minimal methods needed for use with django.core.paginator. Does not support re-ordering or re-filtering across the set. q1 = Thing.objects.filter(foo) q2 = Stuff.objects.filter(bar) qsc = QuerySetChain(q1, q2) init (*subquerysets) count() Performs a.count() for all subquerysets and returns the number of records as an integer Models 13

18 4.7 RankedModel class awl.rankedmodel.models.rankedmodel(*args, **kwargs) Abstract model used to have all the inheritors ordered in the database by this model s rank field. Ranks can either be across all instances of the inheriting model, or in a series of groups. See RankedModel. group_filter for details on implementing grouping. The rank field can be set and saved like any other field. The overridden RankedModel.save method maintains rank integrity. The order is maintained but it is not guaranteed that there are not gaps in the rank count for simplicity re-ordering is not done on deletion. If empty slots are a concern, use RankedModel.repack. Warning: Due to the use of the overridden save() for integrity caution must be employed when dealing with any update() calls or raw SQL as these will not call the save() method. Two admin helper functions are provided so you can do rank re-ording in the django admin. To use the functions, add columns to your admin instances of the inheriting class: from awl.rankedmodel.admintools import (admin_link_move_up, class FavouritesAdmin(admin.ModelAdmin): list_display = ('name', 'rank', 'move_up', 'move_down') def move_up(self, obj): return admin_link_move_up(obj) move_up.allow_tags = True move_up.short_description = 'Move Up Rank' def move_down(self, obj): return admin_link_move_down(obj) move_down.allow_tags = True move_down.short_description = 'Move Down Rank' Parameters rank Ranked order of object init (*args, **kwargs) grouped_filter() This method should be overridden in order to allow groupings of RankModel objects. The default is there is a single group which are all instances of the inheriting class. An example with a grouped model would be: class Grouped(RankedModel): group_number = models.integerfield() def grouped_filter(self): return Grouped.objects.filter( group_number=self.group_number) Returns QuerySet of RankedModel objects that are in the same group. repack() Removes any blank ranks in the order. 14 Chapter 4. Contents

19 save(*args, **kwargs) Overridden method that handles that re-ranking of objects and the integrity of the rank field. Parameters rerank Added parameter, if True will rerank other objects based on the change in this save. Defaults to True. 4.8 RankedModel Admin Two admin helper functions are provided so you can do rank re-ording in the django admin. To use the helper functions you will need to have awl.rankedmodel in your INSTALLED_APPS and include the urls. INSTALLED_APPS = ( 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'awl.rankedmodel', ) urlpatterns = [ url(r'^admin/', include(admin.site.urls)), url(r'^rankedmodel/', include('rankedmodel.urls')), ] The provided functions act return links to a django admin view that can move the associated objects. To use them, add them as columns in the admin model of your inheriting class. from awl.rankedmodel.admin import admin_link_move_up, class FavouritesAdmin(admin.ModelAdmin): list_display = ('name', 'rank', 'move_up', 'move_down') def move_up(self, obj): return admin_link_move_up(obj) move_up.allow_tags = True move_up.short_description = 'Move Up Rank' def move_down(self, obj): return admin_link_move_down(obj) move_down.allow_tags = True move_down.short_description = 'Move Up Rank' awl.rankedmodel.admintools.admin_link_move_down(obj, link_text= down ) Returns a link to a view that moves the passed in object down in rank. Parameters obj Object to move link_text Text to display in the link. Defaults to down Returns HTML link code to view for moving the object awl.rankedmodel.admintools.admin_link_move_up(obj, link_text= up ) Returns a link to a view that moves the passed in object up in rank RankedModel Admin 15

20 Parameters obj Object to move link_text Text to display in the link. Defaults to up Returns HTML link code to view for moving the object 4.9 Template Tags & Filters Custom Django Template Tags and Filters. awl.templatetags.awltags.accessor(parser, token) This template tag is used to do complex nested attribute accessing of an object. The first parameter is the object being accessed, subsequent paramters are one of: a variable in the template context a literal in the template context either of the above surrounded in square brackets For each variable or literal parameter given a getattr is called on the object, chaining to the next parameter. For any sqaure bracket enclosed items the access is done through a dictionary lookup. Example: {% accessor car where 'front_seat' [position] ['fabric'] %} The above would result in the following chain of commands: ref = getattr(car, where) ref = getattr(ref, 'front_seat') ref = ref[position] return ref['fabric'] This tag also supports as syntax, putting the results into a template variable: {% accessor car 'interior' as foo %} awl.templatetags.awltags.getitem(dictionary, keyvar) Custom django template filter that allows access to an item of a dictionary through the key contained in a template variable. Example: context_data = { 'data':{ 'foo':'bar', }, 'key':'foo', } template = Template('{% load awltags %}{{data getitem:key}}') context = Context(context_data) result = template.render(context) >>> result 'bar' 16 Chapter 4. Contents

21 Note: Any KeyErrors are ignored and return an empty string 4.10 Utilities Whenever a developer names something utils it really means stuff I don t know where to put. class awl.utils.urltree A tree representation of the django url paths. Each path is stored in a dictionary with its regex pattern, full path, name (if available) and children. Root items in the tree can be accessed through the children list attribute. init () as_list() Returns a list of strings describing the full paths and patterns along with the name of the urls. Example: print_tree() Convenience method for printing the results of URLTree.as_list to STDOUT awl.utils.get_field_names(obj, ignore_auto=true, ignore_relations=true, exclude=[]) Returns the field names of a Django model object. Parameters obj the Django model class or object instance to get the fields from ignore_auto ignore any fields of type AutoField. Defaults to True ignore_relations ignore any fields that involve relations such as the ForeignKey or ManyToManyField exclude exclude anything in this list from the results Returns generator of found field names awl.utils.get_obj_attr(obj, attr) Works like getattr() but supports django s double underscore object dereference notation. Example usage: >>> get_obj_attr(book, 'writer age') 42 >>> get_obj_attr(book, 'publisher address') <Address object at 105a79ac8> Parameters obj Object to start the derference from attr String name of attribute to return Returns Derferenced object Raises AttributeError in the attribute in question does not exist awl.utils.refetch(obj) Queries the database for the same object that is passed in, refetching its contents in case they are stale. Parameters obj Object to refetch Returns Refreshed version of the object Utilities 17

22 awl.utils.refetch_for_update(obj) Queries the database for the same object that is passed in, refetching its contents and runs select_for_update() to lock the corresponding row until the next commit. Parameters obj Object to refetch Returns Refreshed version of the object awl.utils.render_page(request, page_name, data={}) Deprecated since version 0.12: Use django.shortcuts.render instead This function was a wrapper for render_to_response that handled request context. shortcuts.render method does the same thing, so this just wraps that now. awl.utils.render_page_to_string(request, page_name, data={}) A shortcut for using render_to_string with a RequestContext automatically. The django Waelsteng [wel stæ ] / noun 1. literal: death pole or slaugher pole ; 2. Anglo Saxon tool for impailing enemies or those who had done wrong; 3. A collection of django testing tools Testing Django Views class awl.waelsteng.fakerequest(user=none, method= GET, cookies={}, data={}) Simulates a request object init (user=none, method= GET, cookies={}, data={}) Constructor Parameters user Django User object to include in the request. Defaults to None. If none is given then the parameter is not set at all method Request method. Defaults to GET cookies Dict containing cookies for the request. Defaults to empty data Dict for get or post fields. Defaults to empty Testing Admin Classes awl.waelsteng.create_admin(username= admin, = admin@admin.com, password= admin ) Create and save an admin user. Parameters username Admin account s username. Defaults to admin Admin account s address. Defaults to admin@admin.com password Admin account s password. Defaults to admin Returns Django user with staff and superuser privileges 18 Chapter 4. Contents

23 class awl.waelsteng.admintoolsmixin This mixin is used to help test django admin objects using the django client interface. A superuser is created during setup which can then be used throughout. Note: AdminToolsMixin.initiate must be called in the inheritor s TestCase.setUp method to properly initialize. Once AdminToolsMixin.intiate is called, the following will be available: Parameters site An instance of an AdminSite to test against admin_user A User object with staff and superuser privileges = 'admin@admin.com' Admin account s during the tests PASSWORD = 'admin' Admin account s password during the tests USERNAME = 'admin' Admin account s username during the tests authed_get(url, response_code=200, headers={}, follow=false) Does a django test client get against the given url after logging in the admin first. Parameters url URL to fetch response_code Expected response code from the URL fetch. This value is asserted. Defaults to 200 headers Optional dictionary of headers to send in the request follow When True, the get call will follow any redirect requests. Defaults to False. Returns Django testing Response object authed_post(url, data, response_code=200, follow=false, headers={}) Does a django test client post against the given url after logging in the admin first. Parameters url URL to fetch data Dictionary to form contents to post response_code Expected response code from the URL fetch. This value is asserted. Defaults to 200 headers Optional dictionary of headers to send in with the request Returns Django testing Response object authorize() Authenticates the superuser account via the web login. field_names(admin_model) Returns the names of the fields/columns used by the given admin model. Parameters admin_model Instance of a admin.modeladmin object that is responsible for displaying the change list Waelsteng 19

24 Returns List of field names field_value(admin_model, instance, field_name) Returns the value displayed in the column on the web interface for a given instance. Parameters admin_model Instance of a admin.modeladmin object that is responsible for displaying the change list instance Object instance that is the row in the admin change list Field_name Name of the field/column to fetch initiate() Sets up the AdminSite and creates a user with the appropriate privileges. This should be called from the inheritor s TestCase.setUp method. visit_admin_link(admin_model, instance, field_name, response_code=200, headers={}) This method is used for testing links that are in the change list view of the django admin. For the given instance and field name, the HTML link tags in the column are parsed for a URL and then invoked with AdminToolsMixin.authed_get. Parameters admin_model Instance of a admin.modeladmin object that is responsible for displaying the change list instance Object instance that is the row in the admin change list field_name Name of the field/column to containing the HTML link to get a URL from to visit response_code Expected HTTP status code resulting from the call. The value of this is asserted. Defaults to 200. headers Optional dictionary of headers to send in the request Returns Django test Response object Raises AttributeError If the column does not contain a URL that can be parsed WRunner This is an alternate to DiscoverRunner. Main differences are: Creates and destroys a media directory for uploads during testing Calls a dynamic method for loading test data Allows for short-form versions of test labels Sets static file handling to StaticFilesStorage Like any other runner, you can use it for your django tests by changing your settings: TEST_RUNNER = 'awl.waelsteng.wrunner' Configuration is done inside of the django settings module: WRUNNER = { 'CREATE_TEMP_MEDIA_ROOT':True, 'TEST_DATA':'package.module.function_name' } 20 Chapter 4. Contents

25 If CREATE_TEMP_MEDIA_ROOT is set, then a directory is created and the settings.media_root attribute is changed for the tests. The directory is then destoryed upon test completion. If TEST_DATA is set, then the named function is loaded and run after the database is created. This hook can be used to create test data. Shortcut test labels (using wrench.waelstow.find_shortcut_tests()) are supported by this runner. Any label that starts with = is checked against all tests for substring matches Waelsteng 21

26 22 Chapter 4. Contents

27 CHAPTER 5 Indices and tables genindex modindex search 23

28 24 Chapter 5. Indices and tables

29 Python Module Index a awl.absmodels, 12 awl.admintools, 9 awl.context_processors, 11 awl.css_colours, 11 awl.decorators, 11 awl.models, 12 awl.rankedmodel.admintools, 15 awl.rankedmodel.models, 14 awl.templatetags.awltags, 16 awl.utils, 17 awl.waelsteng, 18 25

30 26 Python Module Index

31 Index Symbols init () (awl.models.querysetchain method), 13 init () (awl.rankedmodel.models.rankedmodel method), 14 init () (awl.utils.urltree method), 17 A accessor() (in module awl.templatetags.awltags), 16 admin_link_move_down() (in module awl.rankedmodel.admintools), 15 admin_link_move_up() (in module awl.rankedmodel.admintools), 15 admin_obj_attr() (in module awl.admintools), 9 admin_obj_link() (in module awl.admintools), 9 AdminToolsMixin (class in awl.waelsteng), 18 as_list() (awl.utils.urltree method), 17 authed_get() (awl.waelsteng.admintoolsmixin method), 19 authed_post() (awl.waelsteng.admintoolsmixin method), 19 authorize() (awl.waelsteng.admintoolsmixin method), 19 awl.absmodels (module), 12 awl.admintools (module), 9 awl.context_processors (module), 11 awl.css_colours (module), 11 awl.decorators (module), 11 awl.models (module), 12 awl.rankedmodel.admintools (module), 15 awl.rankedmodel.models (module), 14 awl.templatetags.awltags (module), 16 awl.utils (module), 17 awl.waelsteng (module), 18 C Choices (class in awl.models), 12 count() (awl.models.querysetchain method), 13 Counter (class in awl.models), 13 create_admin() (in module awl.waelsteng), 18 E (awl.waelsteng.admintoolsmixin attribute), 19 extra_context() (in module awl.context_processors), 11 F field_names() (awl.waelsteng.admintoolsmixin method), 19 field_value() (awl.waelsteng.admintoolsmixin method), 20 G get_field_names() (in module awl.utils), 17 get_obj_attr() (in module awl.utils), 17 getitem() (in module awl.templatetags.awltags), 16 grouped_filter() (awl.rankedmodel.models.rankedmodel method), 14 I increment() (awl.models.counter class method), 13 initiate() (awl.waelsteng.admintoolsmixin method), 20 is_colour() (in module awl.css_colours), 11 L Lock (class in awl.models), 13 lock_until_commit() (awl.models.lock class method), 13 M make_admin_obj_mixin() (in module awl.admintools), 9 P PASSWORD (awl.waelsteng.admintoolsmixin attribute), 19 post_required() (in module awl.decorators), 11 print_tree() (awl.utils.urltree method), 17 Q QuerySetChain (class in awl.models), 13 27

32 R RankedModel (class in awl.rankedmodel.models), 14 refetch() (in module awl.utils), 17 refetch_for_update() (in module awl.utils), 17 render_page() (in module awl.utils), 18 render_page_to_string() (in module awl.utils), 18 repack() (awl.rankedmodel.models.rankedmodel method), 14 S save() (awl.rankedmodel.models.rankedmodel method), 15 T TimeTrackModel (class in awl.absmodels), 12 U URLTree (class in awl.utils), 17 USERNAME (awl.waelsteng.admintoolsmixin attribute), 19 V ValidatingMixin (class in awl.absmodels), 12 visit_admin_link() (awl.waelsteng.admintoolsmixin method), Index