htmlmeta-hub 1.0.0__py3-none-any.whl

htmlmeta_hub/__init__.py

@@ -0,0 +1,198 @@
+# stdlib
+import re
+from typing import Dict
+from typing import Optional
+
+# local
+from metadata_utils import html_attribute_escape
+
+
+__VERSION__ = "1.0.0"
+
+
+# ==============================================================================
+
+
+_http_equivs = ("content-type", "expires", "refresh")
+_link_rels = ("canonical", "link")
+_invalid_attribute_name_character = re.compile(
+    r"""[\x00-\x20"'<>/=\x7f-\x9f\ud800-\udfff\ufdd0-\ufdef]"""
+)
+
+
+def _validate_attribute_name(name: str) -> None:
+    """Reject empty names, HTML delimiters, controls, and invalid code points."""
+    if (
+        not name
+        or _invalid_attribute_name_character.search(name)
+        or any((ord(character) & 0xFFFF) >= 0xFFFE for character in name)
+    ):
+        raise ValueError("Expected a valid HTML attribute name")
+
+
+class HtmlMetaHub(object):
+    data_struct: Dict[str, Dict]
+
+    def __init__(self, **kwargs):
+        """Sets up self.data_struct dict which we use for storage of metadata.
+
+        This package is rather silly, but it affords a consistent way to manage metadata across multiple projects.
+        """
+        self.data_struct = {
+            "http-equiv": {},
+            "name": {},
+            "other": {},
+            "link": {},
+            "_multi": {},  # private namespace for setmulti
+        }
+        self.set_many(**kwargs)
+
+    def set_http_equiv(self, key: str, value: str):
+        self.data_struct["http-equiv"][key] = value
+
+    def set_link(self, rel: str, value: str):
+        self.data_struct["link"][rel] = value
+
+    def set_name(self, key: str, value: str):
+        self.data_struct["name"][key] = value
+
+    def set_other(self, key: str, value: str) -> None:
+        """Set a meta attribute, raising ValueError for a malformed name."""
+        _validate_attribute_name(key)
+        self.data_struct["other"][key] = value
+
+    def set(self, key: str, value: str):
+        """set uses (k,v) as there exists valid meta names which are not kwarg safe"""
+        if key.lower() in _http_equivs:
+            self.data_struct["http-equiv"][key] = value
+        elif key.lower() in _link_rels:
+            self.data_struct["link"][key] = value
+        else:
+            self.data_struct["name"][key] = value
+
+    def set_many(self, **kwargs):
+        """set simply iterates over the **kwargs; here for legacy compatibility"""
+        for key, value in kwargs.items():
+            self.set(key, value)
+
+    def get(self, key: str) -> Optional[str]:
+        if key.lower() in _http_equivs:
+            return self.data_struct["http-equiv"].get(key, None)
+        elif key.lower() in _link_rels:
+            return self.data_struct["link"].get(key, None)
+        else:
+            return self.data_struct["name"].get(key, None)
+
+    def unset(self, key: str):
+        if key.lower() in _http_equivs:
+            if key in self.data_struct["http-equiv"]:
+                del self.data_struct["http-equiv"][key]
+        elif key.lower() in _link_rels:
+            if key in self.data_struct["link"]:
+                del self.data_struct["link"][key]
+        else:
+            if key in self.data_struct["name"]:
+                del self.data_struct["name"][key]
+
+    # --------------------------------------------------------------------------
+    # these are used for multile items.
+    # sometimes you'll have several 'authors' in a link
+
+    def _hasmulti(self, section: str, key: str, value: str) -> bool:
+        if section in self.data_struct["_multi"]:
+            if key in self.data_struct["_multi"][section]:
+                if value in self.data_struct["_multi"][section][key]:
+                    return True
+        return False
+
+    def _setmulti(self, section: str, key: str, value: str):
+        if section not in self.data_struct["_multi"]:
+            self.data_struct["_multi"][section] = {}
+        if key not in self.data_struct["_multi"][section]:
+            self.data_struct["_multi"][section][key] = []
+        if not self._hasmulti(section, key, value):
+            self.data_struct["_multi"][section][key].append(value)
+
+    def _unsetmulti(self, section: str, key: str, value: str):
+        if self._hasmulti(section, key, value):
+            self.data_struct["_multi"][section][key] = [
+                i for i in self.data_struct["_multi"][section][key] if i != value
+            ]
+
+    def _clearmulti(self, section: str, key: str):
+        if section in self.data_struct["_multi"]:
+            if key in self.data_struct["_multi"][section]:
+                del self.data_struct["_multi"][section][key]
+
+    def setmulti_link(self, key: str, value: str):
+        """sets a value for a non-unique key"""
+        self._setmulti("link", key, value)
+
+    def unsetmulti_link(self, key: str, value: str):
+        """unsets a value for a non-unique key"""
+        self._unsetmulti("link", key, value)
+
+    def clearmulti_link(self, key: str):
+        """clears a value for a non-unique key"""
+        self._clearmulti("link", key)
+
+    # --------------------------------------------------------------------------
+
+    def as_html(self) -> str:
+        """helper function. prints out metadata for you.
+
+        You'd probably call it like this in a Mako template:
+            <head>
+                ${meta.as_html()|n}
+            </head>
+
+        Notice that you have to escape under Mako.   For more information on mako escape options - http://www.makotemplates.org/docs/filtering.html
+        """
+        output = []
+        _others = self.data_struct["other"].items()
+        _equivs = self.data_struct["http-equiv"].items()
+        _others_2 = []
+        _equivs_2 = []
+        for k, v in _others:
+            _validate_attribute_name(k)
+            if k.lower() == "charset":
+                output.append(
+                    """<meta %s="%s"/>"""
+                    % (k, html_attribute_escape(v))
+                )
+            else:
+                _others_2.append((k, v))
+        for k, v in _equivs:
+            if "charset" in v.lower():
+                output.append(
+                    """<meta http-equiv="%s" content="%s"/>"""
+                    % (html_attribute_escape(k), html_attribute_escape(v))
+                )
+            else:
+                _equivs_2.append((k, v))
+        for k, v in _equivs_2:
+            output.append(
+                """<meta http-equiv="%s" content="%s"/>"""
+                % (html_attribute_escape(k), html_attribute_escape(v))
+            )
+        for k, v in self.data_struct["name"].items():
+            output.append(
+                """<meta name="%s" content="%s"/>"""
+                % (html_attribute_escape(k), html_attribute_escape(v))
+            )
+        for k, v in _others_2:
+            output.append("""<meta %s="%s"/>""" % (k, html_attribute_escape(v)))
+        for rel, v in self.data_struct["link"].items():
+            output.append(
+                """<link rel="%s" href="%s"/>"""
+                % (html_attribute_escape(rel), html_attribute_escape(v))
+            )
+        if self.data_struct["_multi"]:
+            if "link" in self.data_struct["_multi"]:
+                for rel in self.data_struct["_multi"]["link"]:
+                    for v in self.data_struct["_multi"]["link"][rel]:
+                        output.append(
+                            """<link rel="%s" href="%s"/>"""
+                            % (html_attribute_escape(rel), html_attribute_escape(v))
+                        )
+        return "\n".join(output)

htmlmeta_hub/pyramid_helpers.py

@@ -0,0 +1,25 @@
+# stdlib
+import typing
+
+# local
+from . import HtmlMetaHub
+
+if typing.TYPE_CHECKING:
+    from pyramid.config import Configurator
+    from pyramid.request import Request
+
+# ==============================================================================
+
+
+def includeme(config: "Configurator"):
+    """the pyramid includeme command
+    including this will automatically setup the htmlmeta object for every request
+    """
+    config.add_request_method(
+        "htmlmeta_hub.pyramid_helpers.new_HtmlMetaHub", "htmlmeta", reify=True
+    )
+
+
+def new_HtmlMetaHub(request: "Request"):
+    """simply creates a new hub"""
+    return HtmlMetaHub()

htmlmeta_hub-1.0.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: htmlmeta_hub
+Version: 1.0.0
+Summary: Lightweight support for managing metadata on webpages.
+Home-page: https://github.com/jvanasco/htmlmeta_hub
+Author: Jonathan Vanasco
+Author-email: jvanasco@2xlp.com
+License: MIT
+Keywords: metadata,html,web,pyramid
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: Pyramid
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: metadata_utils>=0.2.0
+Requires-Dist: setuptools<82; python_version >= "3.7" and python_version < "3.10"
+Provides-Extra: testing
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pyramid; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Dynamic: license-file
+
+htmlmeta_hub
+============
+
+Build Status: ![Python package](https://github.com/jvanasco/htmlmeta_hub/workflows/Python%20package/badge.svg)
+
+`htmlmeta_hub` offers lightweight support for managing metadata on webpages.
+
+This package simply and conveniently manages a dict of "metadata"", and renders
+it appropriately.
+
+There are helpers for the Pyramid framework which will attach the metdata object
+to a request, allowing you to build up metadata throughtout the request cycle
+and then finally render.
+
+A typical way to use this package in the Pyramid framework:
+
+
+Include this package in your application's  `__init__.py`:
+
+	def main(global_config, **settings):
+		...
+		# custom htmlmeta
+		config.include("htmlmeta_hub.pyramid_helpers")
+
+
+If you are using "class based views", you can set some default metadata in a core
+handler:
+
+	class Handler(object):
+		def __init__(self,request):
+			self.request = request
+			# set some defaults
+			self.reqesut.htmlmeta.set_many(\
+				title="MyApp",
+				description="awesome",
+				keywords="fun!",
+			)
+
+and then you can add specific metadata in each view's handler:
+
+	class ContentPage(Handler):
+		def view(self):
+		    content= ...
+			self.request.htmlmeta.set('title', content.title)
+			self.request.htmlmeta.set('description', content.description)
+
+In a template, such as this `page.mako` example, you can access specific bits of
+the metadata, or render an entire payload:
+
+	<title>${request.htmlmeta.get('title')|n}</title>
+	${request.htmlmeta.as_html()|n}
+
+
+Pyramid helpers existed until version `0.3.x` but were dropped in favor of the
+`@reify` request method offered by the `config.include` method.
+
+Pylons helpers existed until version `0.1.2` but were dropped.
+
+

htmlmeta_hub-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+htmlmeta_hub/__init__.py,sha256=7s_MNornmfEm8_VwzhN1-E5D3NXBRFm7WcyLddErycA,7461
+htmlmeta_hub/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+htmlmeta_hub/pyramid_helpers.py,sha256=XHM0Yq5qnsKldAvGevMAI2k-bU_wUqSr89ZmJUuh-jo,637
+htmlmeta_hub-1.0.0.dist-info/licenses/LICENSE.txt,sha256=Enmm9ncWfBBUfXnpzvOXiZjo3AzSx8JX7y8MsQz66Kk,1181
+htmlmeta_hub-1.0.0.dist-info/METADATA,sha256=_Vq5U1E9I0dDOnSHPlCi6VsIDyiUSvOuwiAIo_3-hw0,3000
+htmlmeta_hub-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+htmlmeta_hub-1.0.0.dist-info/top_level.txt,sha256=kTgYvlNJFM3qBn1ctfEvOYW0M2l_6ZLU3sOMaa5XuyU,13
+htmlmeta_hub-1.0.0.dist-info/RECORD,,

htmlmeta_hub-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

htmlmeta_hub-1.0.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,23 @@
+The code is licensed as follows:
+
+Copyright (c) 2012, Jonathan Vanasco <jonathan@findmeon.com>
+
+MIT License -- http://www.opensource.org/licenses/mit-license
+
+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.

htmlmeta_hub-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+htmlmeta_hub