{ "info": { "author": "Evan Borgstrom", "author_email": "evan@fatbox.ca", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Natural Language :: English", "Topic :: Software Development :: Libraries", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "FatBox Django Utils\n~~~~~~~~~~~~~~~~~~~\n\nThis is a collection of general utilities for Django projects built by FatBox.\n\nInstallation\n============\n\nInstall using pip::\n\n pip install fatbox-django-utils\n\nIf you're going to use the Template Tags then you also need to add\n``fatbox_utils`` to your ``INSTALLED_APPS`` setting.\n\nThese utilities require Django 1.3+. They may work with earlier versions but\nhaven't been tested.\n\nRendering templates\n===================\n\nrender_to decorator\n-------------------\n\nThe ``render_to`` decorator allows you to very easily render templates from\nyour view functions. Simply decorate your view function and specify the name\nof the template to render to, then return a dict from your view function that\ncontains variables that will be in the context when rendering the template.\n\n.. code-block:: python\n\n from fatbox_utils.decorators import render_to\n\n @render_to('myapp/template.html')\n def myview(request):\n return {\n 'var1': var1,\n 'var2': var2\n }\n\nYou can change the template on the fly by returning a list or tuple where the\nfirst element is the name of the template and the second element is the dict to\nuse for the context.\n\n.. code-block:: python\n\n @render_to('myapp/template.html')\n def myview(request):\n context = {\n 'var1': var1,\n 'var2': var2\n }\n\n # if something is true then use our other template\n if something_is_true:\n return ('other_template.html', context)\n\n # otherwise use the default template\n return context\n\nLastly if you don't return a dict or a list/tuple then ``render_to`` will just\nreturn what you give it. This ensures that if you return things like\n``HttpResponseRedirect`` objects they will work as expected, but also means\nthat you are free to craft your own response should it be required. Anything\nthat's valid to return from a standard Django view will work.\n\nHumanize\n========\n\nhumanize_time function\n----------------------\n\nThe ``humanize_time`` function summarizes time based on the units you provide\nto it. For example here is what is run in the doc tests:\n\n.. code-block:: python\n\n >>> from fatbox_utils.humanize import humanize_time\n >>> humanize_time(173, \"hours\")\n u'1 week, 5 hours'\n >>> humanize_time(17313, \"seconds\")\n u'4 hours, 48 minutes, 33 seconds'\n >>> humanize_time(5400, \"seconds\")\n u'1 hour, 30 minutes'\n >>> humanize_time(90, \"weeks\")\n u'1 year, 10 months, 2 weeks'\n >>> humanize_time(42, \"months\")\n u'3 years, 6 months'\n >>> humanize_time(500, \"days\")\n u'1 year, 5 months, 3 weeks, 3 days'\n\nSee: http://stackoverflow.com/a/6574789\n\nCache\n=====\n\ndelete_template_fragment_cache function\n---------------------------------------\n\nThis is a function that deletes a named template fragment cache.\n\nSee: http://djangosnippets.org/snippets/2723/\n\nIn your template:\n\n.. code-block:: html+django\n\n {% load cache %}\n\n {% cache 3600 my_cache_block request.user.username %}\n ...\n {% endcache %}\n\nAnd in your view:\n\n.. code-block:: python\n\n from fatbox_utils.cache import delete_template_fragment_cache\n\n def my_view(request):\n ...\n delete_template_fragment_cache(\"my_cache_block\", request.user.username)\n ...\n\ni18n / Translation\n==================\n\nThis package includes a number of different utilities for managing and working\nwith i18n / translation in your project.\n\ncurrent_lang context processor\n------------------------------\n\nThis is a context processor that adds ``current_lang`` to your template context\nas a 2 letter language code (ie. ``en``, ``fr``, ``pt``, etc).\n\nJust add ``fatbox_utils.context_processors.current_lang`` to the\n``TEMPLATE_CONTEXT_PROCESSORS`` setting.\n\nManualLanguageMiddleware\n------------------------\n\nThis is a middleware class that allows you to force the language used by the\nDjango translation layer based on a querystring parameter.\n\nTo use it simply add ``fatbox_utils.middleware.ManualLanguageMiddleware`` to\nthe ``MIDDLEWARE_CLASSES`` setting. Then you can pass a two character language\ncode to a get parameter named ``lang`` to activate a specific language.\n\ntranslatable_property for Models\n--------------------------------\n\nOften times when working on a project that deals with multiple languages you\nwant to have certain properties of a model translatable. The\n``translatable_property`` class provides a convenient interface to define your\nproperties that should be available in multiple languages.\n\nConsider the following example ``models.py`` file:\n\n.. code-block:: python\n\n from django.db import models\n from fatbox_utils.i18n import translatable_property, TranslatableModel\n\n class Event(models.Model):\n start = models.DateTimeField()\n end = models.DateTimeField()\n\n title = translatable_property('title', 'translations')\n details = translatable_property('details', 'translations')\n\n class EventTranslation(TranslatableModel):\n event = models.ForeignKey(\n Event,\n related_name='translations'\n )\n title = models.CharField(\n max_length=32\n )\n details = models.TextField()\n\nWhat this does is add two models ``Event`` and ``EventTranslation`` where the\n``EventTranslation`` model has a foreign key to ``Event`` and sets up a related\nmanager named ``translations``.\n\nThe ``EventTranslation`` model extends from ``TranslatableModel`` so that it will\nhave the required ``language`` field setup. The ``language`` field is a CharField\nwith ``max_length=2, choices=settings.LANGUAGES`` set for options. If you require\ndifferent handling for your language selection you can simply extend from Django's\nbase ``models.Model`` and define your own ``language`` field.\n\nOn the ``Event`` model we define two properties using the ``translatable_property``\nclass. When defining these properties the first argument is the field on the\nrelated model and the second argument is the name of the manager that we can use\nto lookup the related model that corresponds to the current language.\n\nWhen you access one of the ``translatable_property`` properties on your model\nit will try to fetch the related object from the ``translations`` manager where\nthe related object has a field named ``language`` that matches the current\nlanguage, as defined by the ``get_language`` function from the\n``django.utils.translation`` package. If it can't find a related object with a\nmatching ``language`` field it will then try to get one with the default\nlanguage, as defined by ``settings.DEFAULT_LANGUAGE``.\n\nPerformance Optimization\n````````````````````````\n\nIf you don't do any optimization of your querysets once you reach even a modest\nnumber of ``Event`` objects iterating over their querysets can become a HUGE\nburden on your database due to the number of SELECT lookups it needs to do when\nfetching all of the related ``EventDescription`` objects.\n\nTo combat this you can use Django's ``prefetch_related`` queryset function to\nfetch all of the related translations in one fell swoop, reducing the number of\nqueries to 2.\n\n.. code-block:: python\n\n Event.objects.filter(...).prefetch_related('translations')\n\nAdmin Integration\n`````````````````\n\nOnce you have your models setup with ``translatable_property`` then you can\nsimply use normal `Django Inlines`_ without having to worry about complex admin\nsite configuration.\n\n.. _Django Inlines: https://docs.djangoproject.com/en/dev/ref/contrib/admin/#inlinemodeladmin-objects\n\nTemplate Tags\n=============\n\nSmart Spaceless\n---------------\n\nThe Django ``{% spaceless %}`` tag is a great way to optimize your templates\nso that you send the smallest amount of data possible to clients, however when\nyou're in development turning spaceless on makes it hard to read your HTML and\ndebug problems.\n\nThe ``{% smart_spaceless %}`` tag works exactly the same as the normal tag,\nexcept that it only applies spaceless when your ``DEBUG`` setting is ``False``.\n\n.. code-block:: html+django\n\n {% load smart_spaceless %}{% smart_spaceless %}\n \n \n ...\n \n {% end_smart_spaceless %}\n\nURL Tools\n---------\n\nThe URL Tools template tags provide some convenience functions when working\nwith URLs in your templates. They all require that the ``request`` be available\nin the current context so make sure that you have\n``django.core.context_processors.request`` enabled in your\n``TEMPLATE_CONTEXT_PROCESSORS`` setting.\n\nbuild_absolute_uri\n``````````````````\n\nThis exposes the ``build_absolute_uri`` function of the request object to your\ntemplates.\n\n.. code-block:: html+django\n\n {% load urltools %}\n\n Link\n\nmodify_querystring\n``````````````````\n\nThis allows you to modify individual querystring parameters, without needing\nto reconstruct the entire URL.\n\nFor example, say you're on a page that shows a listing of objects and you have\nflags for determining if the user will view the results as a grid or as a list.\nOn this same view you may accept a querystring parameter to further limit the\nquery so having to manually reconstruct the URL just to change the format\nbecomes a much more complex task. With ``modify_querystring`` we can change\njust the ``format`` querystring parameter (even adding it if it doesn't exist)\nwithout having to reconstruct anything.\n\n.. code-block:: html+django\n\n {% load urltools %}\n\n
\n Sort:\n By Date |\n Alphabetically\n
\n\n
\n View as:\n List |\n Grid\n
", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/fatbox/fatbox-django-utils", "keywords": null, "license": "UNKNOWN", "maintainer": null, "maintainer_email": null, "name": "fatbox-django-utils", "package_url": "https://pypi.org/project/fatbox-django-utils/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/fatbox-django-utils/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/fatbox/fatbox-django-utils" }, "release_url": "https://pypi.org/project/fatbox-django-utils/1.2/", "requires_dist": null, "requires_python": null, "summary": "A collection of Django utilities, built by FatBox", "version": "1.2" }, "last_serial": 1560802, "releases": { "1.0": [ { "comment_text": "", "digests": { "md5": "d4453095576975ce351097c3d6c51830", "sha256": "46cf93d817dec009db72781a7b3d1cd370bde5b16c32d8b5bbc395ff1dec495d" }, "downloads": -1, "filename": "fatbox-django-utils-1.0.tar.gz", "has_sig": false, "md5_digest": "d4453095576975ce351097c3d6c51830", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 7885, "upload_time": "2013-04-23T20:22:11", "url": "https://files.pythonhosted.org/packages/b4/b9/7f459a2c27650368517ce108e5c56a0239efd277e6e8e6795fdcfa7e19b6/fatbox-django-utils-1.0.tar.gz" } ], "1.1": [ { "comment_text": "", "digests": { "md5": "cff8b262026aae32d6955759e2724c30", "sha256": "daeb859983a6fb5b3dcfced857e5895d4f3dd9ac5c0f8c975a7054c2a5c6c080" }, "downloads": -1, "filename": "fatbox-django-utils-1.1.tar.gz", "has_sig": false, "md5_digest": "cff8b262026aae32d6955759e2724c30", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8910, "upload_time": "2013-05-13T19:28:18", "url": "https://files.pythonhosted.org/packages/dd/83/5fb74e03c9b41cc4ae4c6c410e8590e0cfaa9f3ddfa4e72697e20467defa/fatbox-django-utils-1.1.tar.gz" } ], "1.2": [ { "comment_text": "", "digests": { "md5": "636900ff2d8d3501f3ef9e63788a19c3", "sha256": "b9c79b7e2075418924dff9e59585fe1468af715a62c46b69559a81812ab15dcf" }, "downloads": -1, "filename": "fatbox-django-utils-1.2.tar.gz", "has_sig": false, "md5_digest": "636900ff2d8d3501f3ef9e63788a19c3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9150, "upload_time": "2013-09-12T23:51:47", "url": "https://files.pythonhosted.org/packages/59/a6/c026c015bc966f794f336d852e3e42e6a6ffe1bdea2f541ece4ef4a1f7b4/fatbox-django-utils-1.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "636900ff2d8d3501f3ef9e63788a19c3", "sha256": "b9c79b7e2075418924dff9e59585fe1468af715a62c46b69559a81812ab15dcf" }, "downloads": -1, "filename": "fatbox-django-utils-1.2.tar.gz", "has_sig": false, "md5_digest": "636900ff2d8d3501f3ef9e63788a19c3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9150, "upload_time": "2013-09-12T23:51:47", "url": "https://files.pythonhosted.org/packages/59/a6/c026c015bc966f794f336d852e3e42e6a6ffe1bdea2f541ece4ef4a1f7b4/fatbox-django-utils-1.2.tar.gz" } ] }