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
