{
    "info": {
        "author": "Texas Tribune & The Center for Investigative Reporting",
        "author_email": "dev@armstrongcms.org",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Environment :: Web Environment",
            "Framework :: Django",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Apache Software License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2.6",
            "Programming Language :: Python :: 2.7"
        ],
        "description": "armstrong.apps.embeds\r\n=====================\r\n\r\n.. image:: https://travis-ci.org/armstrong/armstrong.apps.embeds.svg?branch=master\r\n  :target: https://travis-ci.org/armstrong/armstrong.apps.embeds\r\n  :alt: TravisCI status\r\n.. image:: https://coveralls.io/repos/armstrong/armstrong.apps.embeds/badge.png\r\n  :target: https://coveralls.io/r/armstrong/armstrong.apps.embeds\r\n  :alt: Coverage status\r\n.. image:: https://pypip.in/version/armstrong.apps.embeds/badge.png\r\n  :target: https://pypi.python.org/pypi/armstrong.apps.embeds/\r\n  :alt: PyPI Version\r\n.. image:: https://pypip.in/license/armstrong.apps.embeds/badge.png\r\n  :target: https://pypi.python.org/pypi/armstrong.apps.embeds/\r\n  :alt: License\r\n\r\nArmstrong.Apps.Embeds provides a data model and modular backend system to\r\nextract embeddable content and metadata from external URLs. Representing\r\nembeddable content in a database brings the typical benefits of relational\r\ndata. Programmable backends allow more flexible use of the content beyond\r\nthe one-trick pony of the standard \"<iframe>\" copy-paste embed code.\r\n\r\nIntegrating AppsEmbeds into your site will require some work. Mostly because\r\nthis package doesn't make assumptions for *how* you'll be using these\r\nexternal URLs. Maybe you just want to track references to embedded content,\r\nmaybe it's the caching that's interesting or programmatically accessing\r\ncontent provider metadata is what you are after. There's nothing extra to get\r\nin your way, but you'll have to customize code and/or templates.\r\n\r\nThis is a stand alone component; it *does not* require any other pieces of the\r\nArmstrong family. However, it does play nicely with `ArmLayout`_. If you use\r\nArmLayout already, AppsEmbeds is ready to go. Much of the power of AppsEmbeds\r\ncomes from templating so if you use that feature and aren't already using\r\nArmLayout, it's worth considering.\r\n\r\nThe second optional package is `lxml`_, which is necessary if you use the\r\n``resize_iframe`` template filter. Otherwise, this package has three fixed\r\nrequirements to provide model fields and support the backend APIs (currently\r\njust Embedly). See ``package.json`` for these fixed requirements.\r\n\r\n\r\n.. _ArmLayout: https://github.com/armstrong/armstrong.core.arm_layout/\r\n.. _lxml: https://pypi.python.org/pypi/lxml/\r\n\r\nFeatures\r\n--------\r\n- **Single embed, multiple relationships!** Always know where you are using\r\n  external content and the number of references you have.\r\n- **Metadata!** Access the metadata of the external content. Much more useful\r\n  than the vanilla iframe embed code.\r\n- **Modular backends!** Get metadata and embed codes with a standard\r\n  interface to the various content provider APIs.\r\n- **Customizable templates!** Presentation is separate from data. Make that\r\n  external content look appropriate for your site.\r\n- **Single embed, multiple uses!** Create templates for each use case. A video\r\n  can be used as a title, thumbnail, captioned credit, in a gallery, etc.\r\n- **Uniform visual appearance!** Each content type shares templates. Video\r\n  content can be presented in a standard format regardless of the source.\r\n- **Automatic backend assignment!** Program an Embed in one step.\r\n  The URL is all we need.\r\n- **Admin preview!** Examine the response data before saving. Look weird?\r\n  Switch backends and preview again.\r\n- **Response caching!** Worry less about third-party API failure. The\r\n  response is cached indefinitely.\r\n- **Check for new data!** See if new data is available without committing\r\n  to it, right from the Admin.\r\n- **Bird's eye overview!** Aggregate information on how and what types of\r\n  external content you generally use.\r\n\r\n\r\nInstallation & Configuration\r\n----------------------------\r\nSupports Django 1.3, 1.4, 1.5, 1.6, 1.7 on Python 2.6 and 2.7.\r\n(Though if you are using Django 1.3, make sure to use django-model-utils<1.4.)\r\n\r\n#. ``pip install armstrong.apps.embeds``\r\n\r\n#. [optional] ``pip install lxml`` if you plan on using the\r\n   ``resize_iframe`` template filter\r\n\r\n#. [optional] ``pip install armstrong.core.arm_layout`` if you want to use\r\n   ArmLayout to render templates\r\n\r\n#. Add ``armstrong.apps.embeds`` to your ``INSTALLED_APPS``\r\n\r\n#. Install the database schema\r\n\r\n   * Django 1.7+ use ``manage.py migrate``\r\n   * previous Djangos use either ``manage.py syncdb`` or ``manage.py migrate``\r\n     if you are using `South`_ (in which case use South 1.0+)\r\n\r\n#. Load the provided Backends into your database. (This is not provided as\r\n   initial fixture data so that you may edit them without worrying that\r\n   syncdb will restore the initial versions.)\r\n\r\n  ``manage.py loaddata embed_backends.json``\r\n\r\n7. If you are using the Embedly backend, add your API key to ``settings.py``\r\n\r\n  ``EMBEDLY_KEY = 'your key'``\r\n\r\n\r\n**Logging:** This component emits logging statements using the\r\n``armstrong.apps.embeds`` logger.\r\n\r\n.. _South: http://south.aeracode.org/\r\n\r\n\r\nUsage\r\n-----\r\n**A quick overview of the four models--**\r\n\r\n``EmbedType`` and ``Provider`` do essentially nothing besides normalize the\r\ndatabase and provide a quick way to perform aggregation queries. EmbedType is\r\nbased on the four `oEmbed`_ types, though in practice you'll likely have a\r\nfifth ``error`` type (and that's okay).\r\n\r\n``Backend`` is the front-end model for the actual code that connects to\r\nthird-party APIs to retrieve response data for the external content URLs.\r\nIt's easiest to initially load them from the fixture data file but feel free\r\nto customize them as you will. Just don't change the ``slug``, which is how\r\nthe model maps to its code back-end. ``regex`` and ``priority`` are designed\r\nto change. That's how you'll customize the auto-assignment behavior. The\r\nEmbedly backend will handle YouTube sure, but say you've written a more\r\ntargeted YouTube-specific backend--add it to the database with a selective\r\nregex and a higher priority.\r\n\r\n``Embed`` is the cornerstone. Creating a new embed object only requires a\r\n``url``. The backend will auto-assign by regular expression matching the URL\r\nand selecting from the matching backends by highest priority. Auto-assignment\r\nis just a nice feature for faster Embed creation. You can also manually assign\r\na backend on object creation or later. Every other field on the model is\r\nbackend-provided metadata. Consider them read-only. So how do you get a\r\nresponse? How do you get actual information?\r\n\r\n**The Response object--**\r\n\r\n``embed_obj.update_response()`` will retrieve a response from the backend and\r\nassign it if the response is *valid* and *different*, then return ``True``. If\r\nthe response is invalid or the same, no assignment is made and ``False`` is\r\nreturned. If you want the response object itself, use\r\n``embed_obj.get_response()``.\r\n\r\n``embed_obj.response`` is the way to access the response data. This will be a\r\nsubclass of the ``BaseResponse`` object with a standard set of attributes.\r\n``is_valid()`` will be False in cases where the API had a problem, didn't\r\nreturn data, 404'd, etc. ``is_fresh()`` will be True when the response is\r\nfresh off the wire. It's used to differentiate from database cached response\r\ndata and you can probably ignore it. ``type`` and ``provider`` are\r\n``EmbedType`` and ``Provider`` model objects. ``_data`` holds the actual raw\r\nresponse in JSON. The goal is to never directly access this. Instead, the\r\nBaseResponse class is subclassed by each backend/API and tailored to parse the\r\nraw data into standardized attributes. This way who cares if it's YouTube or\r\nVimeo, access the object the same and share the templates. These attributes\r\nreturn an empty string when nothing is available and are therefore\r\n*template safe*. The current data attributes are:\r\n\r\n- ``title``\r\n- ``author_name``\r\n- ``author_url``\r\n- ``image_url``\r\n- ``image_height``\r\n- ``image_width``\r\n- ``render``\r\n\r\n``render`` is perhaps the most important; it is the full expression of the\r\nembedded content that the content provider offers. For Twitter, this is the\r\nblockquote with JavaScript widget that dynamically loads the tweet into an\r\niframe. For YouTube and Vimeo, this is the video player. Whatever way the\r\nservice designs its content to be embedded, this is it.\r\n\r\n``image_xxx`` means different things depending on the content. For a video,\r\nthis will be the still image that shows before the video is played. For\r\nSlideShare, it's the first slide in the presentation. For Flickr, it's the\r\nthumbnail. It's worth noting that we have no idea what the image size will\r\nbe and so if you use this in a template, consider fixing the image tag's\r\ndimensions with attributes or CSS.\r\n\r\n\r\n**Backends--**\r\n\r\n`Embedly`_ is a sort of meta-embed service. They know how to handle over 250\r\ncontent providers to deliver a standardized set of metadata. Specifically this\r\nbackend uses their \"Embed\" service via their `embedly-python`_ library. It\r\noffers a huge benefit but does require an account. Fortunately there is a quite\r\nreasonable free tier. Configuration required to use this is mentioned under the\r\nInstallation section.\r\n\r\n**Twitter** is a simple wrapper for a tag that loads the tweet via Twitter's\r\nJavaScript widget. It does not perform any API or network calls and therefore\r\ndoes not provide any metadata about the URL. The only thing it can do is embed\r\nthe Tweet as if you'd copy-pasted the embed code.\r\n\r\n**Default** just regurgitates the provided URL. It's the catch-all that does\r\nnothing useful.\r\n\r\n\r\n.. _Embedly: http://embed.ly/\r\n.. _embedly-python: https://github.com/embedly/embedly-python/\r\n\r\n**Templates--**\r\n\r\nAssuming you want to display the embed content on your site, this is where\r\nyou'll spend the most developer time. It's not just about what a photo looks\r\nlike versus a video. Now that you have access to more than just the \"embed\r\ncode\"--now that you have metadata--you can use the same embed multiple ways.\r\nFor example, a photo can be used as a preview thumbnail with a small image,\r\na larger image with a title for lead art, a thumbnail in a story that expands\r\ninto a modal full-size version with attribution. Whatever you want. Since\r\nResponse objects have a standard interface, it doesn't even matter where that\r\nphoto came from. Instagram and TwitPic behave the same.\r\n\r\nNote: This concept of provider apathy hinges on the ``EmbedType``. We can only\r\ntreat like types the same or fall back to something generic for all embeds.\r\nIf the provider or the backend reports a Flickr URL as a \"link\" type, even\r\nthough we know in our hearts it's a \"photo\", it won't use the photo-specific\r\ntemplates.\r\n\r\nNow for some examples. Since `ArmLayout`_ was designed for this purpose, we'll\r\nuse it. It provides a ``render_model`` template tag that takes an object and a\r\ntemplate name then looks in a hierarchy from most-specific to least for that\r\ntemplate. ArmLayout uses ``get_layout_template_name()`` for the lookup and\r\nAppsEmbeds has extended it to also look for type-specific templates.\r\n\r\n``render_model embed_obj 'full'`` for a ``photo`` type will look in this order:\r\n\r\n- ``layout/embeds/embedtype/photo/full.html``\r\n- ``layout/embeds/embed/full.html``\r\n\r\nSo to display an Embed object as \"preview\", just make the following files.\r\nEach content type can customize what \"preview\" means. (Maybe a small\r\nthumbnail or truncated intro text.)\r\n\r\n- ``layout/embeds/embedtype/photo/preview.html``\r\n- ``layout/embeds/embedtype/video/preview.html``\r\n- ``layout/embeds/embedtype/link/preview.html``\r\n- ``layout/embeds/embedtype/rich/preview.html``\r\n- ``layout/embeds/embed/preview.html``\r\n\r\n\"Lead art\" could be another way of displaying an embed. (Perhaps a larger\r\nimage along with title and author attribution.)\r\n\r\n- ``layout/embeds/embedtype/photo/lead_art.html``\r\n- ``layout/embeds/embedtype/video/lead_art.html``\r\n- ``layout/embeds/embedtype/link/lead_art.html``\r\n- ``layout/embeds/embedtype/rich/lead_art.html``\r\n- ``layout/embeds/embed/lead_art.html``\r\n\r\nLeave out a type-specific template file and ArmLayout will use the more\r\ngeneral file next in the hierarchy.\r\n\r\nThere's also a ``default.html`` template used as a fallback when the response\r\nis invalid or missing. (This template name can be customized via\r\n``embed_obj.fallback_template_name``.) Without a response, there won't be any\r\ndata to show in the normal/intended template. A fallback can provide more\r\nhelpful output and a visual reference that something isn't right.\r\n\r\n\r\n**Template tags/filters (requires lxml)--**\r\n\r\n``resize_iframe`` is a template filter that caps the width of iframes since\r\nembedding an unexpectedly huge iframe into your layout might break the\r\nappearance. It only shrinks large iframes; it doesn't alter iframes that are\r\nalready the specified size (or smaller).\r\n\r\nCommon usage:\r\n  ``{{ object.response.render|resize_iframe:645|safe }}``\r\n\r\nIn this example, if the ``render`` attribute contains code with iframes and\r\nthe width of any or all of those iframes is larger than 645px, the iframes'\r\nwidth will be changed to 645 and the height will scale smaller accordingly.\r\n\r\n\r\n.. _oEmbed: http://oembed.com/\r\n\r\n\r\nLimitations\r\n-----------\r\n**Content provider terms of service--**\r\n\r\nThe service you are embedding content from may have usage guidelines and\r\nrestrictions. Pay attention and follow these. It may be against their terms\r\nof service to rework or restyle the presentation or to use only pieces of the\r\nmetadata. Changing or reusing things may also be disrespectful and disingenuous\r\nto the content creator. Respect the creator and respect the service.\r\n\r\n**Publishing content--**\r\n\r\nEmbedded content is already published; it's available from some other site.\r\nIt's how we use and integrate that external content into our own works that\r\nmatters here. Armstrong is a platform for newsrooms and content publishers.\r\nThe typical situation is one where reporters and editors write, draft, proof\r\nand publish. Content has eyes on it and doesn't get published until it's\r\nfinished. AppsEmbeds is just the same. A general assumption is that some\r\nhuman is looking at the embed--maybe not the raw response data--but certainly\r\nthe end result of how it looks (i.e. how a template renders it). If it looks\r\nwrong, it doesn't get published.\r\n\r\nIt's likely that someday you'll come across a content provider whose responses\r\ndon't fit the expected form. It's hard to account for these things but\r\nhopefully someone is looking at the content and will notice.\r\n\r\n**Custom API queries--**\r\n\r\nMany APIs provide customization for the responses they provide. They may allow\r\nyou to specify maxwidth and maxheight, alignments for text or localization,\r\ncallbacks, transparency modes or word length truncation. AppsEmbeds doesn't\r\ndo any of that primarily because it can't make those assumptions. AppsEmbeds\r\ngets you the raw data in its default form whatever that may be and follows\r\nthe \"customize after\" approach.\r\n\r\n``resize_iframe`` is an example of this. You may want a 200px iframe for a\r\npreview and an 800px iframe within an article body for the *same* embedded\r\ncontent. It wouldn't do to set a maxwidth=200 on the API call, cache that\r\nand then be stuck for the larger size use case.\r\n\r\nUltimately, API use can be a finicky thing. The best course of action within\r\nthe AppsEmbeds paradigm is to customize or create a backend and/or response\r\nclass fitting the API you use and the parameters you may want to query with.\r\nHave a better idea or an awesome backend? Please make a Pull Request!\r\n\r\n**Different URLs to the same content--**\r\n\r\nThere is currently no way to know if multiple URLs refer to the same content.\r\nThese two YouTube links will make two separate Embed objects::\r\n\r\n  https://www.youtube.com/watch?v=12345\r\n  https://www.youtube.com/watch?v=12345&feature=player_embedded\r\n\r\nContributing\r\n------------\r\nDevelopment occurs on Github. Participation is welcome!\r\n\r\n* Found a bug? File it on `Github Issues`_. Include as much detail as you\r\n  can and make sure to list the specific component since we use a centralized,\r\n  project-wide issue tracker.\r\n* Testing? ``pip install tox`` and run ``tox``\r\n* Have code to submit? Fork the repo, consolidate your changes on a topic\r\n  branch and create a `pull request`_. The `armstrong.dev`_ package provides\r\n  tools for testing, coverage and South migration as well as making it very\r\n  easy to run a full Django environment with this component's settings.\r\n* Questions, need help, discussion? Use our `Google Group`_ mailing list.\r\n\r\n.. _Github Issues: https://github.com/armstrong/armstrong/issues\r\n.. _pull request: http://help.github.com/pull-requests/\r\n.. _armstrong.dev: https://github.com/armstrong/armstrong.dev\r\n.. _Google Group: http://groups.google.com/group/armstrongcms\r\n\r\n\r\nState of Project\r\n----------------\r\n`Armstrong`_ is an open-source news platform that is freely available to any\r\norganization. It is the result of a collaboration between the `Texas Tribune`_\r\nand `The Center for Investigative Reporting`_ and a grant from the\r\n`John S. and James L. Knight Foundation`_. Armstrong is available as a\r\ncomplete bundle and as individual, stand-alone components.\r\n\r\n.. _Armstrong: http://www.armstrongcms.org/\r\n.. _Texas Tribune: http://www.texastribune.org/\r\n.. _The Center for Investigative Reporting: http://cironline.org/\r\n.. _John S. and James L. Knight Foundation: http://www.knightfoundation.org/\r\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://github.com/armstrong/armstrong.apps.embeds/",
        "keywords": null,
        "license": "UNKNOWN",
        "maintainer": null,
        "maintainer_email": null,
        "name": "armstrong.apps.embeds",
        "package_url": "https://pypi.org/project/armstrong.apps.embeds/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/armstrong.apps.embeds/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://github.com/armstrong/armstrong.apps.embeds/"
        },
        "release_url": "https://pypi.org/project/armstrong.apps.embeds/0.9/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Provides a way to store, relate to, extract metadata and embed content from external URLs via a modular backend system",
        "version": "0.9"
    },
    "last_serial": 1216701,
    "releases": {
        "0.8": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5ca627cba735e82b490a8a34f2d2d326",
                    "sha256": "3b87b6b6c5a183916823198721240bc1f3049427e97b0d84ade4e7a1aebef553"
                },
                "downloads": -1,
                "filename": "armstrong.apps.embeds-0.8.tar.gz",
                "has_sig": false,
                "md5_digest": "5ca627cba735e82b490a8a34f2d2d326",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 25938,
                "upload_time": "2014-04-05T02:43:26",
                "url": "https://files.pythonhosted.org/packages/e8/ae/ffe06efb5b95b8ccc6bf675942489961dfbda415f164cdeb26c493aa75c6/armstrong.apps.embeds-0.8.tar.gz"
            }
        ],
        "0.9": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0cc5b6c85db19031eae2a794746b19b2",
                    "sha256": "a266d00bf9be876eca303a8527ddd6ef4be0514749eaa682cd51f11e6cd6bf8a"
                },
                "downloads": -1,
                "filename": "armstrong.apps.embeds-0.9.tar.gz",
                "has_sig": false,
                "md5_digest": "0cc5b6c85db19031eae2a794746b19b2",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 27025,
                "upload_time": "2014-09-08T07:05:37",
                "url": "https://files.pythonhosted.org/packages/89/96/35dd54fb5d95237e84952f8f13e9804cb2dd0a820501af1bee459208d1f4/armstrong.apps.embeds-0.9.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0cc5b6c85db19031eae2a794746b19b2",
                "sha256": "a266d00bf9be876eca303a8527ddd6ef4be0514749eaa682cd51f11e6cd6bf8a"
            },
            "downloads": -1,
            "filename": "armstrong.apps.embeds-0.9.tar.gz",
            "has_sig": false,
            "md5_digest": "0cc5b6c85db19031eae2a794746b19b2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 27025,
            "upload_time": "2014-09-08T07:05:37",
            "url": "https://files.pythonhosted.org/packages/89/96/35dd54fb5d95237e84952f8f13e9804cb2dd0a820501af1bee459208d1f4/armstrong.apps.embeds-0.9.tar.gz"
        }
    ]
}