==================================
Django Template Coverage.py Plugin
==================================
A `coverage.py`_ plugin to measure test coverage of Django templates.
Supported on:
- Python: 3.8 through 3.12.
- Django: 2.x, 3.x and 4.x.
- Coverage.py: 6.x or higher.
The plugin is pip installable::
$ python3 -m pip install django_coverage_plugin
To run it, add this setting to your ``.coveragerc`` file::
[run]
plugins = django_coverage_plugin
Then run your tests under `coverage.py`_.
You will see your templates listed in your coverage report along with
your Python modules. Please use `coverage.py`_ v4.4 or greater to allow
the plugin to identify untested templates.
If you get a :code:`django.core.exceptions.ImproperlyConfigured` error,
you need to set the :code:`DJANGO_SETTINGS_MODULE` environment variable.
Template coverage only works if your Django templates have debugging enabled.
If you get :code:`django_coverage_plugin.plugin.DjangoTemplatePluginException:
Template debugging must be enabled in settings`, or if no templates get
measured, make sure you have :code:`TEMPLATES.OPTIONS.debug` set to True in
your settings file:
.. code-block:: python
TEMPLATES = [
{
...
'OPTIONS': {
'debug': True,
},
},
]
Configuration
~~~~~~~~~~~~~
The Django template plugin uses some existing settings from your
``.coveragerc`` file. The ``source=``, ``include=``, and ``omit=`` options
control what template files are included in the report.
The plugin can find unused template and include them in your results. By
default, it will look for files in your templates directory with an extension
of ``.html``, ``.htm``, or ``.txt``. You can configure it to look for a different set of
extensions if you like::
[run]
plugins = django_coverage_plugin
[django_coverage_plugin]
template_extensions = html, txt, tex, email
If you use ``pyproject.toml`` for tool configuration use::
[tool.coverage.run]
plugins = [
'django_coverage_plugin',
]
[tool.coverage.django_coverage_plugin]
template_extensions = 'html, txt, tex, email'
Caveats
~~~~~~~
Coverage.py can't tell whether a ``{% blocktrans %}`` tag used the
singular or plural text, so both are marked as used if the tag is used.
What the? How?
~~~~~~~~~~~~~~
The technique used to measure the coverage is the same that Dmitry
Trofimov used in `dtcov`_, but integrated into coverage.py as a plugin,
and made more performant. I'd love to see how well it works in a real
production project. If you want to help me with it, feel free to drop me
an email.
The coverage.py plugin mechanism is designed to be generally useful for
hooking into the collection and reporting phases of coverage.py,
specifically to support non-Python files. If you have non-Python files
you'd like to support in coverage.py, let's talk.
Tests
~~~~~
To run the tests::
$ python3 -m pip install -r requirements.txt
$ tox
History
~~~~~~~
.. scriv-insert-here
v3.1.0 — 2023-07-10
-------------------
Dropped support for Python 3.7 and Django 1.x. Declared support for Python
3.12.
v3.0.0 — 2022-12-06
-------------------
Dropped support for Python 2.7, Python 3.6, and Django 1.8.
v2.0.4 — 2022-10-31
-------------------
Declare our support for Python 3.11 and Django 4.1.
v2.0.3 — 2022-05-04
-------------------
Add support for Django 4.0.
v2.0.2 — 2021-11-11
-------------------
If a non-UTF8 file was found when looking for templates, it would fail when
reading during the reporting phase, ending execution. This failure is now
raised in a way that can be ignored with a .coveragerc setting of ``[report]
ignore_errors=True`` (`issue 78`_).
When using ``source=.``, an existing coverage HTML report directory would be
found and believed to be unmeasured HTML template files. This is now fixed.
.. _issue 78: https://github.com/nedbat/django_coverage_plugin/issues/78
v2.0.1 — 2021-10-06
-------------------
Test and claim our support on Python 3.10.
v2.0.0 — 2021-06-08
-------------------
Drop support for Python 3.4 and 3.5.
A setting is available: ``template_extensions`` lets you set the file
extensions that will be considered when looking for unused templates
(requested in `issue 60`_).
Fix an issue on Windows where file names were being compared
case-sensitively, causing templates to be missed (`issue 46`_).
Fix an issue (`issue 63`_) where tag libraries can't be found if imported
during test collection. Thanks to Daniel Izquierdo for the fix.
.. _issue 46: https://github.com/nedbat/django_coverage_plugin/issues/46
.. _issue 60: https://github.com/nedbat/django_coverage_plugin/issues/60
.. _issue 63: https://github.com/nedbat/django_coverage_plugin/issues/63
v1.8.0 — 2020-01-23
-------------------
Add support for:
- Coverage 5
v1.7.0 — 2020-01-16
-------------------
Add support for:
- Python 3.7 & 3.8
- Django 2.2 & 3.0
v1.6.0 — 2018-09-04
-------------------
Add support for Django 2.1.
v1.5.2 — 2017-10-18
-------------------
Validates support for Django version 2.0b1. Improves discovery of
template files.
v1.5.1a — 2017-04-05
--------------------
Validates support for Django version 1.11. Testing for new package
maintainer Pamela McA'Nulty
v1.5.0 — 2017-02-23
-------------------
Removes support for Django versions below 1.8. Validates support for
Django version 1.11b1
v1.4.2 — 2017-02-06
-------------------
Fixes another instance of `issue 32`_, which was the result of an
initialization order problem.
.. _issue 32: https://github.com/nedbat/django_coverage_plugin/issues/32
v1.4.1 — 2017-01-25
-------------------
Fixes `issue 32`_, which was the result of an initialization order
problem.
v1.4 — 2017-01-16
-----------------
Django 1.10.5 is now supported.
Checking settings configuration is deferred so that settings.py is
included in coverage reporting. Fixes `issue 28`_.
Only the ``django.template.backends.django.DjangoTemplates`` template
engine is supported, and it must be configured with
``['OPTIONS']['debug'] = True``. Fixes `issue 27`_.
.. _issue 28: https://github.com/nedbat/django_coverage_plugin/issues/28
.. _issue 27: https://github.com/nedbat/django_coverage_plugin/issues/27
v1.3.1 — 2016-06-02
-------------------
Settings are read slightly differently, so as to not interfere with
programs that don't need settings. Fixes `issue 18`_.
.. _issue 18: https://github.com/nedbat/django_coverage_plugin/issues/18
v1.3 — 2016-04-03
-----------------
Multiple template engines are allowed. Thanks, Simon Charette.
v1.2.2 — 2016-02-01
-------------------
No change in code, but Django 1.9.2 is now supported.
v1.2.1 — 2016-01-28
-------------------
The template debug settings are checked properly for people still using
``TEMPLATE_DEBUG`` in newer versions of Django.
v1.2 — 2016-01-16
-----------------
Check if template debugging is enabled in the settings, and raise a
visible warning if not. This prevents mysterious failures of the
plugin, and fixes `issue 17`_.
Potential Django 1.9 support is included, but the patch to Django hasn't
been applied yet.
.. _issue 17: https://github.com/nedbat/django_coverage_plugin/issues/17
v1.1 — 2015-11-12
-----------------
Explicitly configure settings if need be to get things to work.
v1.0 — 2015-09-20
-----------------
First version :)
.. _coverage.py: http://nedbatchelder.com/code/coverage
.. _dtcov: https://github.com/traff/dtcov
Raw data
{
"_id": null,
"home_page": "https://github.com/nedbat/django_coverage_plugin",
"name": "django-coverage-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Ned Batchelder",
"author_email": "ned@nedbatchelder.com",
"download_url": "https://files.pythonhosted.org/packages/ba/d2/f37452482053e82c47c6ec2626370fe1a2cd81af31e510ad90bb2cb4a081/django_coverage_plugin-3.1.0.tar.gz",
"platform": null,
"description": "==================================\nDjango Template Coverage.py Plugin\n==================================\n\nA `coverage.py`_ plugin to measure test coverage of Django templates.\n\n\n\nSupported on:\n\n- Python: 3.8 through 3.12.\n\n- Django: 2.x, 3.x and 4.x.\n\n- Coverage.py: 6.x or higher.\n\nThe plugin is pip installable::\n\n $ python3 -m pip install django_coverage_plugin\n\nTo run it, add this setting to your ``.coveragerc`` file::\n\n [run]\n plugins = django_coverage_plugin\n\nThen run your tests under `coverage.py`_.\n\nYou will see your templates listed in your coverage report along with\nyour Python modules. Please use `coverage.py`_ v4.4 or greater to allow\nthe plugin to identify untested templates.\n\nIf you get a :code:`django.core.exceptions.ImproperlyConfigured` error,\nyou need to set the :code:`DJANGO_SETTINGS_MODULE` environment variable.\n\nTemplate coverage only works if your Django templates have debugging enabled.\nIf you get :code:`django_coverage_plugin.plugin.DjangoTemplatePluginException:\nTemplate debugging must be enabled in settings`, or if no templates get\nmeasured, make sure you have :code:`TEMPLATES.OPTIONS.debug` set to True in\nyour settings file:\n\n.. code-block:: python\n\n TEMPLATES = [\n {\n ...\n 'OPTIONS': {\n 'debug': True,\n },\n },\n ]\n\n\nConfiguration\n~~~~~~~~~~~~~\n\nThe Django template plugin uses some existing settings from your\n``.coveragerc`` file. The ``source=``, ``include=``, and ``omit=`` options\ncontrol what template files are included in the report.\n\nThe plugin can find unused template and include them in your results. By\ndefault, it will look for files in your templates directory with an extension\nof ``.html``, ``.htm``, or ``.txt``. You can configure it to look for a different set of\nextensions if you like::\n\n [run]\n plugins = django_coverage_plugin\n\n [django_coverage_plugin]\n template_extensions = html, txt, tex, email\n\nIf you use ``pyproject.toml`` for tool configuration use::\n\n [tool.coverage.run]\n plugins = [\n 'django_coverage_plugin',\n ]\n\n [tool.coverage.django_coverage_plugin]\n template_extensions = 'html, txt, tex, email'\n\nCaveats\n~~~~~~~\n\nCoverage.py can't tell whether a ``{% blocktrans %}`` tag used the\nsingular or plural text, so both are marked as used if the tag is used.\n\n\nWhat the? How?\n~~~~~~~~~~~~~~\n\nThe technique used to measure the coverage is the same that Dmitry\nTrofimov used in `dtcov`_, but integrated into coverage.py as a plugin,\nand made more performant. I'd love to see how well it works in a real\nproduction project. If you want to help me with it, feel free to drop me\nan email.\n\nThe coverage.py plugin mechanism is designed to be generally useful for\nhooking into the collection and reporting phases of coverage.py,\nspecifically to support non-Python files. If you have non-Python files\nyou'd like to support in coverage.py, let's talk.\n\n\nTests\n~~~~~\n\nTo run the tests::\n\n $ python3 -m pip install -r requirements.txt\n $ tox\n\n\nHistory\n~~~~~~~\n\n.. scriv-insert-here\n\nv3.1.0 \u2014 2023-07-10\n-------------------\n\nDropped support for Python 3.7 and Django 1.x. Declared support for Python\n3.12.\n\n\nv3.0.0 \u2014 2022-12-06\n-------------------\n\nDropped support for Python 2.7, Python 3.6, and Django 1.8.\n\n\nv2.0.4 \u2014 2022-10-31\n-------------------\n\nDeclare our support for Python 3.11 and Django 4.1.\n\n\nv2.0.3 \u2014 2022-05-04\n-------------------\n\nAdd support for Django 4.0.\n\n\nv2.0.2 \u2014 2021-11-11\n-------------------\n\nIf a non-UTF8 file was found when looking for templates, it would fail when\nreading during the reporting phase, ending execution. This failure is now\nraised in a way that can be ignored with a .coveragerc setting of ``[report]\nignore_errors=True`` (`issue 78`_).\n\nWhen using ``source=.``, an existing coverage HTML report directory would be\nfound and believed to be unmeasured HTML template files. This is now fixed.\n\n.. _issue 78: https://github.com/nedbat/django_coverage_plugin/issues/78\n\n\nv2.0.1 \u2014 2021-10-06\n-------------------\n\nTest and claim our support on Python 3.10.\n\nv2.0.0 \u2014 2021-06-08\n-------------------\n\nDrop support for Python 3.4 and 3.5.\n\nA setting is available: ``template_extensions`` lets you set the file\nextensions that will be considered when looking for unused templates\n(requested in `issue 60`_).\n\nFix an issue on Windows where file names were being compared\ncase-sensitively, causing templates to be missed (`issue 46`_).\n\nFix an issue (`issue 63`_) where tag libraries can't be found if imported\nduring test collection. Thanks to Daniel Izquierdo for the fix.\n\n.. _issue 46: https://github.com/nedbat/django_coverage_plugin/issues/46\n.. _issue 60: https://github.com/nedbat/django_coverage_plugin/issues/60\n.. _issue 63: https://github.com/nedbat/django_coverage_plugin/issues/63\n\nv1.8.0 \u2014 2020-01-23\n-------------------\n\nAdd support for:\n\n- Coverage 5\n\nv1.7.0 \u2014 2020-01-16\n-------------------\n\nAdd support for:\n\n- Python 3.7 & 3.8\n- Django 2.2 & 3.0\n\nv1.6.0 \u2014 2018-09-04\n-------------------\n\nAdd support for Django 2.1.\n\n\nv1.5.2 \u2014 2017-10-18\n-------------------\n\nValidates support for Django version 2.0b1. Improves discovery of\ntemplate files.\n\n\nv1.5.1a \u2014 2017-04-05\n--------------------\n\nValidates support for Django version 1.11. Testing for new package\nmaintainer Pamela McA'Nulty\n\n\nv1.5.0 \u2014 2017-02-23\n-------------------\n\nRemoves support for Django versions below 1.8. Validates support for\nDjango version 1.11b1\n\n\nv1.4.2 \u2014 2017-02-06\n-------------------\n\nFixes another instance of `issue 32`_, which was the result of an\ninitialization order problem.\n\n.. _issue 32: https://github.com/nedbat/django_coverage_plugin/issues/32\n\n\nv1.4.1 \u2014 2017-01-25\n-------------------\n\nFixes `issue 32`_, which was the result of an initialization order\nproblem.\n\n\nv1.4 \u2014 2017-01-16\n-----------------\n\nDjango 1.10.5 is now supported.\n\nChecking settings configuration is deferred so that settings.py is\nincluded in coverage reporting. Fixes `issue 28`_.\n\nOnly the ``django.template.backends.django.DjangoTemplates`` template\nengine is supported, and it must be configured with\n``['OPTIONS']['debug'] = True``. Fixes `issue 27`_.\n\n.. _issue 28: https://github.com/nedbat/django_coverage_plugin/issues/28\n.. _issue 27: https://github.com/nedbat/django_coverage_plugin/issues/27\n\n\n\nv1.3.1 \u2014 2016-06-02\n-------------------\n\nSettings are read slightly differently, so as to not interfere with\nprograms that don't need settings. Fixes `issue 18`_.\n\n.. _issue 18: https://github.com/nedbat/django_coverage_plugin/issues/18\n\n\n\nv1.3 \u2014 2016-04-03\n-----------------\n\nMultiple template engines are allowed. Thanks, Simon Charette.\n\n\n\nv1.2.2 \u2014 2016-02-01\n-------------------\n\nNo change in code, but Django 1.9.2 is now supported.\n\n\n\nv1.2.1 \u2014 2016-01-28\n-------------------\n\nThe template debug settings are checked properly for people still using\n``TEMPLATE_DEBUG`` in newer versions of Django.\n\n\n\nv1.2 \u2014 2016-01-16\n-----------------\n\nCheck if template debugging is enabled in the settings, and raise a\nvisible warning if not. This prevents mysterious failures of the\nplugin, and fixes `issue 17`_.\n\nPotential Django 1.9 support is included, but the patch to Django hasn't\nbeen applied yet.\n\n.. _issue 17: https://github.com/nedbat/django_coverage_plugin/issues/17\n\n\n\nv1.1 \u2014 2015-11-12\n-----------------\n\nExplicitly configure settings if need be to get things to work.\n\n\n\nv1.0 \u2014 2015-09-20\n-----------------\n\nFirst version :)\n\n.. _coverage.py: http://nedbatchelder.com/code/coverage\n.. _dtcov: https://github.com/traff/dtcov\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Django template coverage.py plugin",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://github.com/nedbat/django_coverage_plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c605892bd4cbf2cd2735c1f179bc9bbcac1762f0d505957566f0d39bdcd98a64",
"md5": "8f7e665d6aac3ec8547e3d1cd2757241",
"sha256": "eb0ea8ffdb0db11a02994fc99be6500550efb496c350d709f418ff3d8e553a67"
},
"downloads": -1,
"filename": "django_coverage_plugin-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f7e665d6aac3ec8547e3d1cd2757241",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14054,
"upload_time": "2023-07-10T13:14:44",
"upload_time_iso_8601": "2023-07-10T13:14:44.735951Z",
"url": "https://files.pythonhosted.org/packages/c6/05/892bd4cbf2cd2735c1f179bc9bbcac1762f0d505957566f0d39bdcd98a64/django_coverage_plugin-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bad2f37452482053e82c47c6ec2626370fe1a2cd81af31e510ad90bb2cb4a081",
"md5": "02a76d1fc973537f97f35c3fcb8f3a17",
"sha256": "223d34bf92bebadcb8b7b89932480e41c7bd98b44a8156934488fbe7f4a71f99"
},
"downloads": -1,
"filename": "django_coverage_plugin-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "02a76d1fc973537f97f35c3fcb8f3a17",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13799,
"upload_time": "2023-07-10T13:14:46",
"upload_time_iso_8601": "2023-07-10T13:14:46.322253Z",
"url": "https://files.pythonhosted.org/packages/ba/d2/f37452482053e82c47c6ec2626370fe1a2cd81af31e510ad90bb2cb4a081/django_coverage_plugin-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 13:14:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nedbat",
"github_project": "django_coverage_plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "tox",
"specs": [
[
">=",
"1.8"
]
]
},
{
"name": "build",
"specs": []
},
{
"name": "scriv",
"specs": []
},
{
"name": "twine",
"specs": []
}
],
"tox": true,
"lcname": "django-coverage-plugin"
}
JSON
