pinterest-url-normalizer 0.1.0__tar.gz

pinterest_url_normalizer-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+verified-dist/

pinterest_url_normalizer-0.1.0/LICENSE

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

pinterest_url_normalizer-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pinterest-url-normalizer
+Version: 0.1.0
+Summary: Parse, classify, and normalize Pinterest URLs without network requests
+Project-URL: Homepage, https://savepinner.com/pinterest-downloader/
+Project-URL: Source, https://github.com/jiankn/pinterest-url-normalizer-python
+Project-URL: Issues, https://github.com/jiankn/pinterest-url-normalizer-python/issues
+Project-URL: TypeScript package, https://jsr.io/@savepinner/pinterest-url-normalizer
+Author: SavePinner contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: normalizer,parser,pinterest,url,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pinterest-url-normalizer
+
+Parse, classify, and normalize Pinterest URLs without making network requests.
+
+[SavePinner](https://savepinner.com/pinterest-downloader/) · [TypeScript package on JSR](https://jsr.io/@savepinner/pinterest-url-normalizer) · [Source code](https://github.com/jiankn/pinterest-url-normalizer-python)
+
+The package recognizes Pin, `pin.it`, profile, board, and Ideas URLs across Pinterest country domains. It uses an exact host allow list, rejects HTTP URLs and lookalike domains, and removes tracking parameters from normalized output.
+
+## Install
+
+```bash
+python -m pip install pinterest-url-normalizer
+```
+
+## Python API
+
+```python
+from pinterest_url_normalizer import (
+    is_pinterest_url,
+    normalize_pinterest_url,
+    parse_pinterest_url,
+)
+
+parsed = parse_pinterest_url("https://de.pinterest.com/pin/987654321/?utm_source=share")
+
+print(parsed.kind)  # pin
+print(parsed.pin_id)  # 987654321
+print(parsed.normalized_url)  # https://www.pinterest.com/pin/987654321/
+
+is_pinterest_url("https://pin.it/AbC123")
+normalize_pinterest_url("https://pinterest.co.uk/savepinner/media-tools/")
+```
+
+## Command line
+
+Normalize URL arguments:
+
+```bash
+pinterest-url-normalizer \
+  "https://pinterest.co.uk/pin/123/?utm_source=share" \
+  "https://pin.it/AbC123"
+```
+
+Or pipe one URL per line and emit JSON Lines:
+
+```bash
+printf '%s\n' 'https://www.pinterest.com/pin/123/' | \
+  pinterest-url-normalizer --json
+```
+
+The command exits with status `1` when any input is invalid and `2` when no input is provided.
+
+## Supported URL kinds
+
+| Kind | Example |
+| --- | --- |
+| `pin` | `https://www.pinterest.com/pin/123456789/` |
+| `short` | `https://pin.it/AbC123` |
+| `profile` | `https://www.pinterest.com/savepinner/` |
+| `board` | `https://www.pinterest.com/savepinner/media-tools/` |
+| `ideas` | `https://www.pinterest.com/ideas/space-wallpaper/926295399832/` |
+
+`pin.it` links are classified and normalized but are not followed. Resolving them requires a network request and belongs in the consuming application.
+
+## API
+
+- `parse_pinterest_url(value)` returns an immutable `ParsedPinterestUrl`. It raises `PinterestUrlError` with code `INVALID_URL` or `UNSUPPORTED_URL` on failure.
+- `normalize_pinterest_url(value)` returns the canonical URL.
+- `is_pinterest_url(value)` validates a supported URL form.
+- `is_pinterest_host(host)` checks a hostname against the exact country-domain allow list.
+
+## Why this package exists
+
+This parser is maintained by the team behind [SavePinner](https://savepinner.com/pinterest-downloader/), a browser tool for inspecting media exposed by public Pinterest Pin URLs. The package contains no downloader, tracking, browser automation, or remote code.
+
+Pinterest is a trademark of Pinterest, Inc. This project is independent and is not affiliated with or endorsed by Pinterest.
+
+## License
+
+MIT

pinterest_url_normalizer-0.1.0/README.md

@@ -0,0 +1,80 @@
+# pinterest-url-normalizer
+
+Parse, classify, and normalize Pinterest URLs without making network requests.
+
+[SavePinner](https://savepinner.com/pinterest-downloader/) · [TypeScript package on JSR](https://jsr.io/@savepinner/pinterest-url-normalizer) · [Source code](https://github.com/jiankn/pinterest-url-normalizer-python)
+
+The package recognizes Pin, `pin.it`, profile, board, and Ideas URLs across Pinterest country domains. It uses an exact host allow list, rejects HTTP URLs and lookalike domains, and removes tracking parameters from normalized output.
+
+## Install
+
+```bash
+python -m pip install pinterest-url-normalizer
+```
+
+## Python API
+
+```python
+from pinterest_url_normalizer import (
+    is_pinterest_url,
+    normalize_pinterest_url,
+    parse_pinterest_url,
+)
+
+parsed = parse_pinterest_url("https://de.pinterest.com/pin/987654321/?utm_source=share")
+
+print(parsed.kind)  # pin
+print(parsed.pin_id)  # 987654321
+print(parsed.normalized_url)  # https://www.pinterest.com/pin/987654321/
+
+is_pinterest_url("https://pin.it/AbC123")
+normalize_pinterest_url("https://pinterest.co.uk/savepinner/media-tools/")
+```
+
+## Command line
+
+Normalize URL arguments:
+
+```bash
+pinterest-url-normalizer \
+  "https://pinterest.co.uk/pin/123/?utm_source=share" \
+  "https://pin.it/AbC123"
+```
+
+Or pipe one URL per line and emit JSON Lines:
+
+```bash
+printf '%s\n' 'https://www.pinterest.com/pin/123/' | \
+  pinterest-url-normalizer --json
+```
+
+The command exits with status `1` when any input is invalid and `2` when no input is provided.
+
+## Supported URL kinds
+
+| Kind | Example |
+| --- | --- |
+| `pin` | `https://www.pinterest.com/pin/123456789/` |
+| `short` | `https://pin.it/AbC123` |
+| `profile` | `https://www.pinterest.com/savepinner/` |
+| `board` | `https://www.pinterest.com/savepinner/media-tools/` |
+| `ideas` | `https://www.pinterest.com/ideas/space-wallpaper/926295399832/` |
+
+`pin.it` links are classified and normalized but are not followed. Resolving them requires a network request and belongs in the consuming application.
+
+## API
+
+- `parse_pinterest_url(value)` returns an immutable `ParsedPinterestUrl`. It raises `PinterestUrlError` with code `INVALID_URL` or `UNSUPPORTED_URL` on failure.
+- `normalize_pinterest_url(value)` returns the canonical URL.
+- `is_pinterest_url(value)` validates a supported URL form.
+- `is_pinterest_host(host)` checks a hostname against the exact country-domain allow list.
+
+## Why this package exists
+
+This parser is maintained by the team behind [SavePinner](https://savepinner.com/pinterest-downloader/), a browser tool for inspecting media exposed by public Pinterest Pin URLs. The package contains no downloader, tracking, browser automation, or remote code.
+
+Pinterest is a trademark of Pinterest, Inc. This project is independent and is not affiliated with or endorsed by Pinterest.
+
+## License
+
+MIT

pinterest_url_normalizer-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pinterest-url-normalizer"
+version = "0.1.0"
+description = "Parse, classify, and normalize Pinterest URLs without network requests"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "SavePinner contributors" }]
+keywords = ["pinterest", "url", "normalizer", "parser", "validation"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://savepinner.com/pinterest-downloader/"
+Source = "https://github.com/jiankn/pinterest-url-normalizer-python"
+Issues = "https://github.com/jiankn/pinterest-url-normalizer-python/issues"
+"TypeScript package" = "https://jsr.io/@savepinner/pinterest-url-normalizer"
+
+[project.scripts]
+pinterest-url-normalizer = "pinterest_url_normalizer.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pinterest_url_normalizer"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/LICENSE",
+  "/README.md",
+  "/pyproject.toml",
+]

pinterest_url_normalizer-0.1.0/src/pinterest_url_normalizer/__init__.py

@@ -0,0 +1,27 @@
+"""Public API for pinterest-url-normalizer."""
+
+from .core import (
+    PINTEREST_HOSTS,
+    ParsedPinterestUrl,
+    PinterestUrlError,
+    PinterestUrlErrorCode,
+    PinterestUrlKind,
+    is_pinterest_host,
+    is_pinterest_url,
+    normalize_pinterest_url,
+    parse_pinterest_url,
+)
+
+__all__ = [
+    "PINTEREST_HOSTS",
+    "ParsedPinterestUrl",
+    "PinterestUrlError",
+    "PinterestUrlErrorCode",
+    "PinterestUrlKind",
+    "is_pinterest_host",
+    "is_pinterest_url",
+    "normalize_pinterest_url",
+    "parse_pinterest_url",
+]
+
+__version__ = "0.1.0"

pinterest_url_normalizer-0.1.0/src/pinterest_url_normalizer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pinterest_url_normalizer-0.1.0/src/pinterest_url_normalizer/cli.py

@@ -0,0 +1,76 @@
+"""Command-line interface for pinterest-url-normalizer."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from dataclasses import asdict
+from typing import TextIO
+
+from .core import PinterestUrlError, parse_pinterest_url
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pinterest-url-normalizer",
+        description="Normalize Pinterest URLs without making network requests.",
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "urls",
+        metavar="URL",
+        nargs="*",
+        help="URL to normalize; reads one URL per stdin line when omitted",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="write one JSON object per input URL",
+    )
+    return parser
+
+
+def _stdin_urls(stream: TextIO) -> list[str]:
+    return [line.strip() for line in stream if line.strip()]
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line interface and return its process exit code."""
+
+    args = _parser().parse_args(argv)
+    urls = args.urls or _stdin_urls(sys.stdin)
+    if not urls:
+        print("error: provide at least one URL or pipe URLs on stdin", file=sys.stderr)
+        return 2
+
+    exit_code = 0
+    for value in urls:
+        try:
+            parsed = parse_pinterest_url(value)
+        except PinterestUrlError as error:
+            exit_code = 1
+            if args.json:
+                print(
+                    json.dumps(
+                        {
+                            "valid": False,
+                            "input": value,
+                            "error": str(error),
+                            "error_code": error.code,
+                        },
+                        separators=(",", ":"),
+                    )
+                )
+            else:
+                print(f"{value}: {error.code}: {error}", file=sys.stderr)
+            continue
+
+        if args.json:
+            payload = {"valid": True, **asdict(parsed)}
+            print(json.dumps(payload, separators=(",", ":")))
+        else:
+            print(parsed.normalized_url)
+
+    return exit_code

pinterest_url_normalizer-0.1.0/src/pinterest_url_normalizer/core.py

@@ -0,0 +1,283 @@
+"""Parse and normalize supported Pinterest URL forms without network access."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+from urllib.parse import urlsplit
+
+COUNTRY_HOSTS = (
+    "pinterest.at",
+    "pinterest.be",
+    "pinterest.ca",
+    "pinterest.ch",
+    "pinterest.cl",
+    "pinterest.co",
+    "pinterest.co.kr",
+    "pinterest.co.nz",
+    "pinterest.co.uk",
+    "pinterest.com.au",
+    "pinterest.com.br",
+    "pinterest.com.mx",
+    "pinterest.com.pe",
+    "pinterest.com.tr",
+    "pinterest.cz",
+    "pinterest.de",
+    "pinterest.dk",
+    "pinterest.es",
+    "pinterest.fi",
+    "pinterest.fr",
+    "pinterest.gr",
+    "pinterest.hu",
+    "pinterest.id",
+    "pinterest.ie",
+    "pinterest.it",
+    "pinterest.jp",
+    "pinterest.nl",
+    "pinterest.no",
+    "pinterest.ph",
+    "pinterest.pl",
+    "pinterest.pt",
+    "pinterest.ro",
+    "pinterest.se",
+    "pinterest.sk",
+)
+
+REGIONAL_SUBDOMAINS = (
+    "at",
+    "au",
+    "be",
+    "br",
+    "ca",
+    "ch",
+    "cl",
+    "co",
+    "cz",
+    "de",
+    "dk",
+    "es",
+    "fi",
+    "fr",
+    "gr",
+    "hu",
+    "id",
+    "ie",
+    "it",
+    "jp",
+    "kr",
+    "mx",
+    "nl",
+    "no",
+    "nz",
+    "pe",
+    "ph",
+    "pl",
+    "pt",
+    "ro",
+    "se",
+    "sk",
+    "tr",
+    "uk",
+)
+
+PINTEREST_HOSTS = frozenset(
+    (
+        "pinterest.com",
+        "www.pinterest.com",
+        "m.pinterest.com",
+        *COUNTRY_HOSTS,
+        *(f"www.{host}" for host in COUNTRY_HOSTS),
+        *(f"{region}.pinterest.com" for region in REGIONAL_SUBDOMAINS),
+    )
+)
+
+RESERVED_FIRST_SEGMENTS = frozenset(
+    {
+        "business",
+        "categories",
+        "explore",
+        "help",
+        "ideas",
+        "login",
+        "logout",
+        "oauth",
+        "pin",
+        "pin-builder",
+        "resource",
+        "search",
+        "settings",
+        "signup",
+        "today",
+        "topics",
+    }
+)
+
+CANONICAL_HOST = "www.pinterest.com"
+SHORT_HOST = "pin.it"
+PIN_PATH_RE = re.compile(
+    r"^/pin/(?:(\d{1,20})|[A-Za-z0-9][A-Za-z0-9_-]*--(\d{1,20}))(?:/[A-Za-z0-9_-]*)?/?$"
+)
+SHORT_PATH_RE = re.compile(r"^/([A-Za-z0-9]{2,})/?$")
+IDEAS_PATH_RE = re.compile(r"^/ideas/([A-Za-z0-9][A-Za-z0-9_-]*)/(\d{1,20})/?$")
+USERNAME_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$")
+BOARD_SLUG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+
+PinterestUrlKind = Literal["pin", "short", "profile", "board", "ideas"]
+PinterestUrlErrorCode = Literal["INVALID_URL", "UNSUPPORTED_URL"]
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedPinterestUrl:
+    """A supported Pinterest URL and its canonical representation."""
+
+    kind: PinterestUrlKind
+    original_url: str
+    normalized_url: str
+    host: str
+    pin_id: str | None = None
+    shortcode: str | None = None
+    username: str | None = None
+    board_slug: str | None = None
+    idea_slug: str | None = None
+    idea_id: str | None = None
+
+
+class PinterestUrlError(ValueError):
+    """Raised when a URL is invalid or has an unsupported Pinterest path."""
+
+    def __init__(self, code: PinterestUrlErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _parse_https_url(value: str) -> tuple[str, str, str]:
+    if not isinstance(value, str):
+        raise PinterestUrlError("INVALID_URL", "URL must be a string")
+
+    original_url = value.strip()
+    if not original_url or len(original_url) > 2048:
+        raise PinterestUrlError("INVALID_URL", "URL is empty or too long")
+
+    try:
+        parsed = urlsplit(original_url)
+        host = parsed.hostname.lower() if parsed.hostname else ""
+        port = parsed.port
+    except ValueError as error:
+        raise PinterestUrlError("INVALID_URL", "URL could not be parsed") from error
+
+    if parsed.scheme.lower() != "https" or not host:
+        raise PinterestUrlError("INVALID_URL", "Only HTTPS URLs are supported")
+    if (
+        port not in (None, 443)
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise PinterestUrlError(
+            "INVALID_URL", "Credentials and non-standard ports are not supported"
+        )
+
+    return original_url, host, parsed.path
+
+
+def is_pinterest_host(host: str) -> bool:
+    """Return whether *host* is in the exact Pinterest host allow list."""
+
+    return isinstance(host, str) and host.lower() in PINTEREST_HOSTS
+
+
+def parse_pinterest_url(value: str) -> ParsedPinterestUrl:
+    """Parse a supported Pinterest URL and return its normalized fields."""
+
+    original_url, host, path = _parse_https_url(value)
+
+    if host == SHORT_HOST:
+        match = SHORT_PATH_RE.fullmatch(path)
+        if not match:
+            raise PinterestUrlError("UNSUPPORTED_URL", "Unsupported pin.it path")
+        shortcode = match.group(1)
+        return ParsedPinterestUrl(
+            kind="short",
+            original_url=original_url,
+            normalized_url=f"https://{SHORT_HOST}/{shortcode}/",
+            host=SHORT_HOST,
+            shortcode=shortcode,
+        )
+
+    if not is_pinterest_host(host):
+        raise PinterestUrlError(
+            "INVALID_URL", "Host is not an allowed Pinterest domain"
+        )
+
+    pin_match = PIN_PATH_RE.fullmatch(path)
+    if pin_match:
+        pin_id = pin_match.group(1) or pin_match.group(2)
+        return ParsedPinterestUrl(
+            kind="pin",
+            original_url=original_url,
+            normalized_url=f"https://{CANONICAL_HOST}/pin/{pin_id}/",
+            host=CANONICAL_HOST,
+            pin_id=pin_id,
+        )
+
+    ideas_match = IDEAS_PATH_RE.fullmatch(path)
+    if ideas_match:
+        idea_slug, idea_id = ideas_match.groups()
+        return ParsedPinterestUrl(
+            kind="ideas",
+            original_url=original_url,
+            normalized_url=f"https://{CANONICAL_HOST}/ideas/{idea_slug}/{idea_id}/",
+            host=CANONICAL_HOST,
+            idea_slug=idea_slug,
+            idea_id=idea_id,
+        )
+
+    segments = [segment for segment in path.split("/") if segment]
+    first_segment = segments[0].lower() if segments else ""
+    if not first_segment or first_segment in RESERVED_FIRST_SEGMENTS:
+        raise PinterestUrlError("UNSUPPORTED_URL", "Unsupported Pinterest path")
+
+    if len(segments) == 1 and USERNAME_RE.fullmatch(segments[0]):
+        username = segments[0]
+        return ParsedPinterestUrl(
+            kind="profile",
+            original_url=original_url,
+            normalized_url=f"https://{CANONICAL_HOST}/{username}/",
+            host=CANONICAL_HOST,
+            username=username,
+        )
+
+    if (
+        len(segments) == 2
+        and USERNAME_RE.fullmatch(segments[0])
+        and BOARD_SLUG_RE.fullmatch(segments[1])
+    ):
+        username, board_slug = segments
+        return ParsedPinterestUrl(
+            kind="board",
+            original_url=original_url,
+            normalized_url=f"https://{CANONICAL_HOST}/{username}/{board_slug}/",
+            host=CANONICAL_HOST,
+            username=username,
+            board_slug=board_slug,
+        )
+
+    raise PinterestUrlError("UNSUPPORTED_URL", "Unsupported Pinterest path")
+
+
+def normalize_pinterest_url(value: str) -> str:
+    """Return the canonical representation of a supported Pinterest URL."""
+
+    return parse_pinterest_url(value).normalized_url
+
+
+def is_pinterest_url(value: object) -> bool:
+    """Return whether *value* is a supported Pinterest URL."""
+
+    if not isinstance(value, str):
+        return False
+    try:
+        parse_pinterest_url(value)
+    except PinterestUrlError:
+        return False
+    return True

pinterest_url_normalizer-0.1.0/src/pinterest_url_normalizer/py.typed

@@ -0,0 +1 @@
+

pinterest_url_normalizer-0.1.0/tests/test_cli.py

@@ -0,0 +1,42 @@
+import io
+import json
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from unittest.mock import patch
+
+from pinterest_url_normalizer.cli import main
+
+
+class CliTests(unittest.TestCase):
+    def test_normalizes_positional_urls(self) -> None:
+        stdout = io.StringIO()
+        with redirect_stdout(stdout):
+            exit_code = main(["https://pinterest.co.uk/pin/123/?utm_source=test"])
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(stdout.getvalue(), "https://www.pinterest.com/pin/123/\n")
+
+    def test_reads_stdin_and_reports_json_lines(self) -> None:
+        stdout = io.StringIO()
+        stdin = io.StringIO("https://pin.it/AbC123\nhttps://example.com/pin/123/\n")
+        with patch("sys.stdin", stdin), redirect_stdout(stdout):
+            exit_code = main(["--json"])
+
+        rows = [json.loads(line) for line in stdout.getvalue().splitlines()]
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(rows[0]["valid"], True)
+        self.assertEqual(rows[0]["normalized_url"], "https://pin.it/AbC123/")
+        self.assertEqual(rows[1]["valid"], False)
+        self.assertEqual(rows[1]["error_code"], "INVALID_URL")
+
+    def test_requires_input(self) -> None:
+        stderr = io.StringIO()
+        with patch("sys.stdin", io.StringIO()), redirect_stderr(stderr):
+            exit_code = main([])
+
+        self.assertEqual(exit_code, 2)
+        self.assertIn("provide at least one URL", stderr.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

pinterest_url_normalizer-0.1.0/tests/test_core.py

@@ -0,0 +1,86 @@
+import unittest
+
+from pinterest_url_normalizer import (
+    PinterestUrlError,
+    is_pinterest_host,
+    is_pinterest_url,
+    normalize_pinterest_url,
+    parse_pinterest_url,
+)
+
+
+class PinterestUrlNormalizerTests(unittest.TestCase):
+    def test_parses_and_normalizes_pin_urls(self) -> None:
+        parsed = parse_pinterest_url(
+            "https://de.pinterest.com/pin/987654321/?utm_source=test"
+        )
+
+        self.assertEqual(parsed.kind, "pin")
+        self.assertEqual(parsed.pin_id, "987654321")
+        self.assertEqual(
+            parsed.original_url,
+            "https://de.pinterest.com/pin/987654321/?utm_source=test",
+        )
+        self.assertEqual(
+            parsed.normalized_url, "https://www.pinterest.com/pin/987654321/"
+        )
+        self.assertEqual(parsed.host, "www.pinterest.com")
+
+    def test_extracts_id_from_slugged_pin_urls(self) -> None:
+        parsed = parse_pinterest_url(
+            "https://www.pinterest.com/pin/roasted-pineapple-chicken--68746366275/"
+        )
+
+        self.assertEqual(parsed.kind, "pin")
+        self.assertEqual(parsed.pin_id, "68746366275")
+
+    def test_recognizes_short_urls_without_resolving_them(self) -> None:
+        parsed = parse_pinterest_url("https://pin.it/AbC123?source=share")
+
+        self.assertEqual(parsed.kind, "short")
+        self.assertEqual(parsed.shortcode, "AbC123")
+        self.assertEqual(parsed.normalized_url, "https://pin.it/AbC123/")
+
+    def test_classifies_profile_board_and_ideas_urls(self) -> None:
+        profile = parse_pinterest_url("https://pinterest.com/savepinner/")
+        board = parse_pinterest_url("https://www.pinterest.com/savepinner/media-tools/")
+        ideas = parse_pinterest_url(
+            "https://www.pinterest.com/ideas/space-wallpaper-4k/926295399832/"
+        )
+
+        self.assertEqual(profile.kind, "profile")
+        self.assertEqual(profile.username, "savepinner")
+        self.assertEqual(board.kind, "board")
+        self.assertEqual(board.username, "savepinner")
+        self.assertEqual(board.board_slug, "media-tools")
+        self.assertEqual(ideas.kind, "ideas")
+        self.assertEqual(ideas.idea_slug, "space-wallpaper-4k")
+        self.assertEqual(ideas.idea_id, "926295399832")
+
+    def test_rejects_lookalikes_http_credentials_ports_and_reserved_paths(self) -> None:
+        invalid = (
+            "https://www.pinterest.com.evil.example/pin/123/",
+            "http://www.pinterest.com/pin/123/",
+            "https://user:pass@www.pinterest.com/pin/123/",
+            "https://www.pinterest.com:8443/pin/123/",
+            "https://www.pinterest.com/search/pins/?q=cats",
+        )
+
+        for value in invalid:
+            with self.subTest(value=value):
+                self.assertFalse(is_pinterest_url(value))
+                with self.assertRaises(PinterestUrlError):
+                    parse_pinterest_url(value)
+
+    def test_exposes_normalization_and_host_helpers(self) -> None:
+        self.assertEqual(
+            normalize_pinterest_url("https://pinterest.co.uk/pin/123/?foo=bar"),
+            "https://www.pinterest.com/pin/123/",
+        )
+        self.assertTrue(is_pinterest_host("PINTEREST.CO.UK"))
+        self.assertFalse(is_pinterest_host("pinterest.co.uk.evil.example"))
+        self.assertFalse(is_pinterest_url(None))
+
+
+if __name__ == "__main__":
+    unittest.main()