django-snakeoil


Namedjango-snakeoil JSON
Version 2.0 PyPI version JSON
download
home_pageNone
SummarySimple SEO & meta tag management for Django
upload_time2024-10-09 12:52:58
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseMIT License Copyright (c) 2020 Tom Carrick Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords django seo meta
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ===============
django-snakeoil
===============

django-snakeoil helps manage your ``<meta>`` tags. It works on all supported
Django versions and databases.

It offers full internationalization support (tags for multiple languages),
content set dynamically from object attributes, automatic Opengraph image
width and heights for ``ImageField``, and more.

`Full documentation <https://django-snakeoil.readthedocs.io/en/latest/index.html>`_

Getting started
===============

To install, ``pip install django-snakeoil`` or use your favourite package
manager.

You can use Snakeoil in two ways. If you'd like to attach metadata to an
object, you can use the model abstract base class:

.. code-block:: python

    from snakeoil.models import SEOModel

    class Article(SEOModel):
        title = models.CharField(max_length=200)
        author = models.ForeignKey(User, on_delete=models.CASCADE)
        main_image = models.Imagefield(blank=True, null=True)

        @property
        def author_name(self):
            return

        @property
        def snakeoil_metadata(self):
            metadata = {
                "default": [
                    {
                        "name": "author",
                        "content": self.author.get_full_name(),
                    },
                    {"property": "og:title", "content": self.title},
                ]
            }
            if self.main_image:
                metadata["default"].append(
                    {"property": "og:image", "attribute": "main_image"}
                )
            return metadata

You can also override these tags in the admin per-object.

For situations where you can't change the model (flatpages, third party apps)
or don't have one at all, there is an ``SEOPath`` model that maps paths to
your meta tags.

Tags are added in the admin (or however else you like) as JSON. For example:

.. code-block:: JSON

    {
        "default": [
            {"name": "description", "property": "og:description", "content": "Meta description"},
            {"property": "og:title", "content": "My blog post"},
            {"name": "author", "attribute": "author_name"},
            {"property": "og:image", "static": "img/default.jpg"}
        ]
    }

Where ``default`` will work for any language. You can replace ``default``
with a language code, e.g. "nl_NL", and these tags will only display if the
current language is Dutch. This will generate something like:

.. code-block:: html

    <meta name="description" property="og:description" content="Meta description">
    <meta property="og:title" "content="My blog post">
    <!-- from my_object.author_name -->
    <meta name="author" content="Tom Carrick">
    <!-- build a static URL -->
    <meta property="og:image" content="/static/img/default.jpg">

Note that when using ``static``, width and height are not added, but you may
add these yourself. For ``ImageField``, this will be added automatically:

.. code-block:: JSON

    {
        "default": [
            {"property": "og:image", "attribute": "main_image"}
        ]
    }

Results in:

.. code-block:: html

    <meta property="og:image" content="/media/blog_1_main_image.jpg">
    <meta property="og:image:width" content="640">
    <meta property="og:image:height" content="480">

Django Templates
----------------

Add ``snakeoil`` to your ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS = [
        "snakeoil",
        # ...
    ]

In your base template, add this where you want the tags to appear:

.. code-block:: html

    {% load snakeoil %}
    {% block head %}
        {% meta %}
    {% endblock %}

This will automatically find an object based on the ``get_absolute_url()``
of your model, by looking in the request context. If nothing is found,
snakeoil will check for an ``SEOPath`` object for the current path. If
you have an object, it is recommended to pass it into the tag directly
to short-circuit the tag finding mechanisms:

.. code-block:: html

    {% meta my_obj %}

Jinja2
------

Set your environment:

.. code-block:: python

    from jinja2 import Environment
    from snakeoil.jinja2 import get_meta_tags

    def environment(**options):
        env = Environment(**options)
        env.globals.update(
            {
                "get_meta_tags": get_meta_tags,
                # ...
            }
        )
        return env

In your template:

.. code-block:: html

    {% block meta %}
        {% with meta_tags=get_meta_tags() %}
            {% include "snakeoil/seo.jinja2" %}
        {% endwith %}
    {% endblock meta %}

To pass in an object:

.. code-block:: html

    {% block meta %}
        {% with meta_tags=get_meta_tags(my_object) %}
            {% include "snakeoil/seo.jinja2" %}
        {% endwith %}
    {% endblock meta %}

Notes
=====

Thanks to kezabelle for the name. For those wondering:

Metadata is often used for SEO purposes. A lot of people (rightly or not)
consider SEO to be snakeoil. Also, SnakEOil. Very clever, I know.

The old version of django-snakeoil can be found on the ``old`` branch, but
won't be updated.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "django-snakeoil",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "django, seo, meta",
    "author": null,
    "author_email": "Tom Carrick <tom@carrick.eu>",
    "download_url": "https://files.pythonhosted.org/packages/8e/14/b1a618a8fca2d7b9c137e7da00fe702570edd596d6cae270ac8612dbcf57/django_snakeoil-2.0.tar.gz",
    "platform": null,
    "description": "===============\ndjango-snakeoil\n===============\n\ndjango-snakeoil helps manage your ``<meta>`` tags. It works on all supported\nDjango versions and databases.\n\nIt offers full internationalization support (tags for multiple languages),\ncontent set dynamically from object attributes, automatic Opengraph image\nwidth and heights for ``ImageField``, and more.\n\n`Full documentation <https://django-snakeoil.readthedocs.io/en/latest/index.html>`_\n\nGetting started\n===============\n\nTo install, ``pip install django-snakeoil`` or use your favourite package\nmanager.\n\nYou can use Snakeoil in two ways. If you'd like to attach metadata to an\nobject, you can use the model abstract base class:\n\n.. code-block:: python\n\n    from snakeoil.models import SEOModel\n\n    class Article(SEOModel):\n        title = models.CharField(max_length=200)\n        author = models.ForeignKey(User, on_delete=models.CASCADE)\n        main_image = models.Imagefield(blank=True, null=True)\n\n        @property\n        def author_name(self):\n            return\n\n        @property\n        def snakeoil_metadata(self):\n            metadata = {\n                \"default\": [\n                    {\n                        \"name\": \"author\",\n                        \"content\": self.author.get_full_name(),\n                    },\n                    {\"property\": \"og:title\", \"content\": self.title},\n                ]\n            }\n            if self.main_image:\n                metadata[\"default\"].append(\n                    {\"property\": \"og:image\", \"attribute\": \"main_image\"}\n                )\n            return metadata\n\nYou can also override these tags in the admin per-object.\n\nFor situations where you can't change the model (flatpages, third party apps)\nor don't have one at all, there is an ``SEOPath`` model that maps paths to\nyour meta tags.\n\nTags are added in the admin (or however else you like) as JSON. For example:\n\n.. code-block:: JSON\n\n    {\n        \"default\": [\n            {\"name\": \"description\", \"property\": \"og:description\", \"content\": \"Meta description\"},\n            {\"property\": \"og:title\", \"content\": \"My blog post\"},\n            {\"name\": \"author\", \"attribute\": \"author_name\"},\n            {\"property\": \"og:image\", \"static\": \"img/default.jpg\"}\n        ]\n    }\n\nWhere ``default`` will work for any language. You can replace ``default``\nwith a language code, e.g. \"nl_NL\", and these tags will only display if the\ncurrent language is Dutch. This will generate something like:\n\n.. code-block:: html\n\n    <meta name=\"description\" property=\"og:description\" content=\"Meta description\">\n    <meta property=\"og:title\" \"content=\"My blog post\">\n    <!-- from my_object.author_name -->\n    <meta name=\"author\" content=\"Tom Carrick\">\n    <!-- build a static URL -->\n    <meta property=\"og:image\" content=\"/static/img/default.jpg\">\n\nNote that when using ``static``, width and height are not added, but you may\nadd these yourself. For ``ImageField``, this will be added automatically:\n\n.. code-block:: JSON\n\n    {\n        \"default\": [\n            {\"property\": \"og:image\", \"attribute\": \"main_image\"}\n        ]\n    }\n\nResults in:\n\n.. code-block:: html\n\n    <meta property=\"og:image\" content=\"/media/blog_1_main_image.jpg\">\n    <meta property=\"og:image:width\" content=\"640\">\n    <meta property=\"og:image:height\" content=\"480\">\n\nDjango Templates\n----------------\n\nAdd ``snakeoil`` to your ``INSTALLED_APPS``:\n\n.. code-block:: python\n\n    INSTALLED_APPS = [\n        \"snakeoil\",\n        # ...\n    ]\n\nIn your base template, add this where you want the tags to appear:\n\n.. code-block:: html\n\n    {% load snakeoil %}\n    {% block head %}\n        {% meta %}\n    {% endblock %}\n\nThis will automatically find an object based on the ``get_absolute_url()``\nof your model, by looking in the request context. If nothing is found,\nsnakeoil will check for an ``SEOPath`` object for the current path. If\nyou have an object, it is recommended to pass it into the tag directly\nto short-circuit the tag finding mechanisms:\n\n.. code-block:: html\n\n    {% meta my_obj %}\n\nJinja2\n------\n\nSet your environment:\n\n.. code-block:: python\n\n    from jinja2 import Environment\n    from snakeoil.jinja2 import get_meta_tags\n\n    def environment(**options):\n        env = Environment(**options)\n        env.globals.update(\n            {\n                \"get_meta_tags\": get_meta_tags,\n                # ...\n            }\n        )\n        return env\n\nIn your template:\n\n.. code-block:: html\n\n    {% block meta %}\n        {% with meta_tags=get_meta_tags() %}\n            {% include \"snakeoil/seo.jinja2\" %}\n        {% endwith %}\n    {% endblock meta %}\n\nTo pass in an object:\n\n.. code-block:: html\n\n    {% block meta %}\n        {% with meta_tags=get_meta_tags(my_object) %}\n            {% include \"snakeoil/seo.jinja2\" %}\n        {% endwith %}\n    {% endblock meta %}\n\nNotes\n=====\n\nThanks to kezabelle for the name. For those wondering:\n\nMetadata is often used for SEO purposes. A lot of people (rightly or not)\nconsider SEO to be snakeoil. Also, SnakEOil. Very clever, I know.\n\nThe old version of django-snakeoil can be found on the ``old`` branch, but\nwon't be updated.\n",
    "bugtrack_url": null,
    "license": "MIT License  Copyright (c) 2020 Tom Carrick  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
    "summary": "Simple SEO & meta tag management for Django",
    "version": "2.0",
    "project_urls": {
        "Documentation": "https://django-snakeoil.readthedocs.io/en/latest/",
        "Homepage": "https://github.com/knyghty/django-snakeoil",
        "Repository": "https://github.com/knyghty/django-snakeoil"
    },
    "split_keywords": [
        "django",
        " seo",
        " meta"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "7957899fb4d389705c04d4694c8866b11109d0e05b21c52e6341e272c11174d6",
                "md5": "2cfbf78130455bc44b33dd442a9b569b",
                "sha256": "19b6f28beafe4e743877f1df0f5bf7184b56bfe285f484860ba6c4f336646d79"
            },
            "downloads": -1,
            "filename": "django_snakeoil-2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2cfbf78130455bc44b33dd442a9b569b",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 11212,
            "upload_time": "2024-10-09T12:52:57",
            "upload_time_iso_8601": "2024-10-09T12:52:57.171444Z",
            "url": "https://files.pythonhosted.org/packages/79/57/899fb4d389705c04d4694c8866b11109d0e05b21c52e6341e272c11174d6/django_snakeoil-2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "8e14b1a618a8fca2d7b9c137e7da00fe702570edd596d6cae270ac8612dbcf57",
                "md5": "74672ff93a148cef384081a79c43bc4c",
                "sha256": "f8194d971af029ef5107171328ebd741e197d204055f719250ccb31423c78cac"
            },
            "downloads": -1,
            "filename": "django_snakeoil-2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "74672ff93a148cef384081a79c43bc4c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 13831,
            "upload_time": "2024-10-09T12:52:58",
            "upload_time_iso_8601": "2024-10-09T12:52:58.660378Z",
            "url": "https://files.pythonhosted.org/packages/8e/14/b1a618a8fca2d7b9c137e7da00fe702570edd596d6cae270ac8612dbcf57/django_snakeoil-2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-10-09 12:52:58",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "knyghty",
    "github_project": "django-snakeoil",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "lcname": "django-snakeoil"
}
        
Elapsed time: 4.43937s