trustlist-badge 0.1.0__tar.gz

trustlist_badge-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+*.log
+.DS_Store
+*.tgz
+bin/
+obj/
+dist/
+__pycache__/
+*.egg-info/
+target/
+vendor/
+.phpunit.result.cache

trustlist_badge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TrustList
+
+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.

trustlist_badge-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: trustlist-badge
+Version: 0.1.0
+Summary: Show your TrustList rank badge on your website: the badge image, linked to the ranking it cites.
+Project-URL: Homepage, https://trustlist.uk/developers
+Project-URL: Source, https://github.com/eharain/trustlist-public/tree/main/packages/python
+Project-URL: Specification, https://github.com/eharain/trustlist-public/blob/main/spec/badge.md
+Author: TrustList
+License-Expression: MIT
+License-File: LICENSE
+Keywords: badge,ranking,reviews,trustlist
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# trustlist-badge
+
+Show your TrustList rank badge on your website from Python. If your business is ranked on
+[TrustList](https://trustlist.uk), this package builds the badge snippet: the badge image, linked to the
+ranking it cites, with a small Verify link. Print it in your page's HTML so every visitor and search
+engine sees the link.
+
+```sh
+pip install trustlist-badge
+```
+
+```python
+from trustlist_badge import badge_html
+
+html = badge_html(
+    type="company",                          # or "product"
+    slug="your-company",                     # from your TrustList address
+    page="/best/web-design-agency/london",   # the ranking's path
+    label="TrustList: Top Web Design Agencies in London",
+)
+```
+
+In Django or Jinja templates, mark it safe (`mark_safe(html)` or `{{ html|safe }}`): the function
+escapes every value itself. `badge_url`, `ranking_url` and `verify_url` return the separate links;
+invalid input raises `BadgeError`.
+
+The badge is built by TrustList from the published edition; it updates itself with each edition and
+reads "Not ranked" if the rank it cites is gone. Same behaviour in every language: see the
+[specification](https://github.com/eharain/trustlist-public/blob/main/spec/badge.md). MIT licence.

trustlist_badge-0.1.0/README.md

@@ -0,0 +1,29 @@
+# trustlist-badge
+
+Show your TrustList rank badge on your website from Python. If your business is ranked on
+[TrustList](https://trustlist.uk), this package builds the badge snippet: the badge image, linked to the
+ranking it cites, with a small Verify link. Print it in your page's HTML so every visitor and search
+engine sees the link.
+
+```sh
+pip install trustlist-badge
+```
+
+```python
+from trustlist_badge import badge_html
+
+html = badge_html(
+    type="company",                          # or "product"
+    slug="your-company",                     # from your TrustList address
+    page="/best/web-design-agency/london",   # the ranking's path
+    label="TrustList: Top Web Design Agencies in London",
+)
+```
+
+In Django or Jinja templates, mark it safe (`mark_safe(html)` or `{{ html|safe }}`): the function
+escapes every value itself. `badge_url`, `ranking_url` and `verify_url` return the separate links;
+invalid input raises `BadgeError`.
+
+The badge is built by TrustList from the published edition; it updates itself with each edition and
+reads "Not ranked" if the rank it cites is gone. Same behaviour in every language: see the
+[specification](https://github.com/eharain/trustlist-public/blob/main/spec/badge.md). MIT licence.

trustlist_badge-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trustlist-badge"
+version = "0.1.0"
+description = "Show your TrustList rank badge on your website: the badge image, linked to the ranking it cites."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+authors = [{ name = "TrustList" }]
+keywords = ["trustlist", "badge", "ranking", "reviews"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+
+[project.urls]
+Homepage = "https://trustlist.uk/developers"
+Source = "https://github.com/eharain/trustlist-public/tree/main/packages/python"
+Specification = "https://github.com/eharain/trustlist-public/blob/main/spec/badge.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trustlist_badge"]

trustlist_badge-0.1.0/src/trustlist_badge/__init__.py

@@ -0,0 +1,82 @@
+"""Build TrustList rank badge links: the badge image URL, the ranking it links to, the verify URL,
+and a ready-to-print HTML snippet. See spec/badge.md in https://github.com/eharain/trustlist-public.
+
+    from trustlist_badge import badge_html
+    html = badge_html(type="company", slug="your-company", page="/best/web-design-agency/london")
+"""
+
+import re
+from urllib.parse import quote
+
+__all__ = ["ranking_url", "badge_url", "verify_url", "badge_html", "BadgeError"]
+__version__ = "0.1.0"
+
+_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_SIZES = {"regular": (320, 64), "small": (240, 48)}
+
+
+class BadgeError(ValueError):
+    """Raised for an unknown type, a malformed slug, a page outside /best/ or an unknown size."""
+
+
+def _check(type, slug, page, size):
+    if type not in ("company", "product"):
+        raise BadgeError('type must be "company" or "product"')
+    if not slug or not _SLUG.match(slug):
+        raise BadgeError("slug must be lowercase letters, digits and hyphens")
+    if not page or not page.startswith("/best/"):
+        raise BadgeError("page must start with /best/")
+    if size not in _SIZES:
+        raise BadgeError('size must be "regular" or "small"')
+
+
+def _base(base):
+    return (base or "https://trustlist.uk").rstrip("/")
+
+
+def _enc(value):
+    # The same characters as JavaScript's encodeURIComponent leaves alone.
+    return quote(value, safe="-_.!~*'()")
+
+
+def _query(type, slug, page, edition):
+    parts = [("type", type), ("slug", slug), ("page", page)]
+    if edition:
+        parts.append(("edition", edition))
+    return "&".join(f"{k}={_enc(v)}" for k, v in parts)
+
+
+def ranking_url(type, slug, page, edition=None, base=None, size="regular"):
+    """The ranking page the badge cites."""
+    _check(type, slug, page, size)
+    return _base(base) + page
+
+
+def badge_url(type, slug, page, edition=None, base=None, size="regular"):
+    """The badge image, built by TrustList from the published edition."""
+    _check(type, slug, page, size)
+    return f"{_base(base)}/badges/rank?{_query(type, slug, page, edition)}"
+
+
+def verify_url(type, slug, page, edition=None, base=None, size="regular"):
+    """TrustList's record of the rank the badge cites."""
+    _check(type, slug, page, size)
+    return f"{_base(base)}/badges/verify?{_query(type, slug, page, edition)}"
+
+
+def _esc(s):
+    return (s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+             .replace('"', "&quot;").replace("'", "&#39;"))
+
+
+def badge_html(type, slug, page, edition=None, base=None, size="regular", label=None):
+    """The snippet to print: the badge linking to its ranking, and a small Verify link."""
+    _check(type, slug, page, size)
+    w, h = _SIZES[size]
+    args = dict(type=type, slug=slug, page=page, edition=edition, base=base, size=size)
+    return (
+        f'<a href="{_esc(ranking_url(**args))}" title="See this ranking on TrustList">'
+        f'<img src="{_esc(badge_url(**args))}" width="{w}" height="{h}" alt="{_esc(label or "TrustList rank badge")}" '
+        f'loading="lazy" style="border:0;max-width:100%;height:auto"></a> '
+        f'<a href="{_esc(verify_url(**args))}" style="font:11px system-ui,sans-serif;color:#64748b">Verify</a>'
+    )

trustlist_badge-0.1.0/tests/badge-vectors.json

@@ -0,0 +1,79 @@
+{
+  "valid": [
+    {
+      "input": {
+        "type": "company",
+        "slug": "acme-ltd",
+        "page": "/best/web-design-agency/london"
+      },
+      "rankingUrl": "https://trustlist.uk/best/web-design-agency/london",
+      "badgeUrl": "https://trustlist.uk/badges/rank?type=company&slug=acme-ltd&page=%2Fbest%2Fweb-design-agency%2Flondon",
+      "verifyUrl": "https://trustlist.uk/badges/verify?type=company&slug=acme-ltd&page=%2Fbest%2Fweb-design-agency%2Flondon",
+      "badgeHtml": "<a href=\"https://trustlist.uk/best/web-design-agency/london\" title=\"See this ranking on TrustList\"><img src=\"https://trustlist.uk/badges/rank?type=company&amp;slug=acme-ltd&amp;page=%2Fbest%2Fweb-design-agency%2Flondon\" width=\"320\" height=\"64\" alt=\"TrustList rank badge\" loading=\"lazy\" style=\"border:0;max-width:100%;height:auto\"></a> <a href=\"https://trustlist.uk/badges/verify?type=company&amp;slug=acme-ltd&amp;page=%2Fbest%2Fweb-design-agency%2Flondon\" style=\"font:11px system-ui,sans-serif;color:#64748b\">Verify</a>"
+    },
+    {
+      "input": {
+        "type": "product",
+        "slug": "postgresql",
+        "page": "/best/rdbms-software/sql",
+        "edition": "2026-Q4"
+      },
+      "rankingUrl": "https://trustlist.uk/best/rdbms-software/sql",
+      "badgeUrl": "https://trustlist.uk/badges/rank?type=product&slug=postgresql&page=%2Fbest%2Frdbms-software%2Fsql&edition=2026-Q4",
+      "verifyUrl": "https://trustlist.uk/badges/verify?type=product&slug=postgresql&page=%2Fbest%2Frdbms-software%2Fsql&edition=2026-Q4",
+      "badgeHtml": "<a href=\"https://trustlist.uk/best/rdbms-software/sql\" title=\"See this ranking on TrustList\"><img src=\"https://trustlist.uk/badges/rank?type=product&amp;slug=postgresql&amp;page=%2Fbest%2Frdbms-software%2Fsql&amp;edition=2026-Q4\" width=\"320\" height=\"64\" alt=\"TrustList rank badge\" loading=\"lazy\" style=\"border:0;max-width:100%;height:auto\"></a> <a href=\"https://trustlist.uk/badges/verify?type=product&amp;slug=postgresql&amp;page=%2Fbest%2Frdbms-software%2Fsql&amp;edition=2026-Q4\" style=\"font:11px system-ui,sans-serif;color:#64748b\">Verify</a>"
+    },
+    {
+      "input": {
+        "type": "company",
+        "slug": "acme-ltd",
+        "page": "/best/accounting-firm/united-kingdom",
+        "size": "small",
+        "base": "https://example.test/",
+        "label": "Top Accounting Firms in the UK & \"more\" <test>"
+      },
+      "rankingUrl": "https://example.test/best/accounting-firm/united-kingdom",
+      "badgeUrl": "https://example.test/badges/rank?type=company&slug=acme-ltd&page=%2Fbest%2Faccounting-firm%2Funited-kingdom",
+      "verifyUrl": "https://example.test/badges/verify?type=company&slug=acme-ltd&page=%2Fbest%2Faccounting-firm%2Funited-kingdom",
+      "badgeHtml": "<a href=\"https://example.test/best/accounting-firm/united-kingdom\" title=\"See this ranking on TrustList\"><img src=\"https://example.test/badges/rank?type=company&amp;slug=acme-ltd&amp;page=%2Fbest%2Faccounting-firm%2Funited-kingdom\" width=\"240\" height=\"48\" alt=\"Top Accounting Firms in the UK &amp; &quot;more&quot; &lt;test&gt;\" loading=\"lazy\" style=\"border:0;max-width:100%;height:auto\"></a> <a href=\"https://example.test/badges/verify?type=company&amp;slug=acme-ltd&amp;page=%2Fbest%2Faccounting-firm%2Funited-kingdom\" style=\"font:11px system-ui,sans-serif;color:#64748b\">Verify</a>"
+    }
+  ],
+  "invalid": [
+    {
+      "input": {
+        "type": "person",
+        "slug": "acme-ltd",
+        "page": "/best/x"
+      }
+    },
+    {
+      "input": {
+        "type": "company",
+        "slug": "Acme Ltd",
+        "page": "/best/x"
+      }
+    },
+    {
+      "input": {
+        "type": "company",
+        "slug": "",
+        "page": "/best/x"
+      }
+    },
+    {
+      "input": {
+        "type": "company",
+        "slug": "acme-ltd",
+        "page": "/top/x"
+      }
+    },
+    {
+      "input": {
+        "type": "company",
+        "slug": "acme-ltd",
+        "page": "/best/x",
+        "size": "huge"
+      }
+    }
+  ]
+}

trustlist_badge-0.1.0/tests/test_vectors.py

@@ -0,0 +1,31 @@
+import json
+import pathlib
+import unittest
+
+from trustlist_badge import BadgeError, badge_html, badge_url, ranking_url, verify_url
+
+VECTORS = json.loads((pathlib.Path(__file__).parent / "badge-vectors.json").read_text(encoding="utf-8"))
+
+
+def args(inp):
+    return dict(type=inp.get("type"), slug=inp.get("slug"), page=inp.get("page"), edition=inp.get("edition"),
+                base=inp.get("base"), size=inp.get("size", "regular"))
+
+
+class VectorTests(unittest.TestCase):
+    def test_valid(self):
+        for case in VECTORS["valid"]:
+            a = args(case["input"])
+            self.assertEqual(ranking_url(**a), case["rankingUrl"])
+            self.assertEqual(badge_url(**a), case["badgeUrl"])
+            self.assertEqual(verify_url(**a), case["verifyUrl"])
+            self.assertEqual(badge_html(**a, label=case["input"].get("label")), case["badgeHtml"])
+
+    def test_invalid(self):
+        for case in VECTORS["invalid"]:
+            with self.assertRaises(BadgeError):
+                badge_html(**args(case["input"]))
+
+
+if __name__ == "__main__":
+    unittest.main()