fastsaver 0.1.0__tar.gz

fastsaver-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environments (any local venv: venv/, .venv/, .venv39/, .venv-smoke/ ...)
+venv*/
+.venv*/
+.env
+.env.*
+!.env.example
+
+# uv
+uv.lock
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local
+.claude/
+*.log

fastsaver-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- `save()` treats a destination written with a trailing slash (`"downloads/"`) as a
+  directory and creates it on demand; the temporary `.part` file now has a unique,
+  exclusively created name and derived file names are sanitised for Windows too.
+- API calls never follow redirects, even with a user-supplied `httpx` client that has
+  `follow_redirects=True`; an unexpected 3xx is reported as `APIError` with a
+  `base_url` hint.
+- Client-side argument errors raise `InvalidArgumentError` (a `FastSaverError` **and**
+  a `ValueError`), so one `except FastSaverError` covers bad input too.
+- HTTP 429 is retried with a slower backoff (2 s, 4 s) and `Retry-After` HTTP-dates are
+  understood; non-finite values are ignored.
+- Using a closed client raises `ConfigurationError` instead of a raw `RuntimeError`.
+- `YouTubeInfo.available_formats` is sorted (`audio`, `144p` … `2160p`) and
+  `best_video_format` was added; `Track.thumbnail_url`, `MediaResult.thumbnail` and
+  `MediaItem.thumbnail` aliases; `FetchError.upstream_status` for `fetch.error: <status>`.
+- `TimeoutArg`, `FileInput`, `InvalidArgumentError` and `parse_duration_seconds` are
+  exported from the package root; `fastsaver youtube tg-audio` accepts the aliases
+  `tg-bot` and `audio-for-bot`.
+- `shazam.identify()` reads inputs with a 50 MiB cap and rejects non-regular files.
+
+## [0.1.0] - 2026-09-05
+
+Initial public release.
+
+### Added
+
+- `FastSaver` (sync) and `AsyncFastSaver` (async) clients with identical method
+  names and signatures, context-manager support and bring-your-own `httpx` client.
+- Full coverage of the FastSaverAPI v1 endpoints:
+  - `client.fetch(url)` — Instagram (posts, reels, stories, highlights), TikTok
+    (no watermark), Pinterest, Facebook, X/Twitter, RuTube and Likee.
+  - `client.youtube.info()`, `client.youtube.search()`, `client.youtube.download()`
+    (audio/MP3 and 144p–2160p) and `client.youtube.audio_for_bot()` (Telegram `file_id`).
+  - `client.shazam.identify()`, `client.shazam.top()` and `client.shazam.lyrics()`.
+  - `client.balance()` — plan, credits and rate limit of the current key.
+  - `client.save(url, dest)` — stream any `download_url` (tunnel or CDN) to disk
+    without leaking the API key.
+- Typed, frozen dataclass models (`MediaResult`, `MediaItem`, `Music`, `YouTubeInfo`,
+  `YouTubeSearch`, `YouTubeDownload`, `TelegramAudio`, `ShazamMatch`, `ShazamTop`,
+  `Track`, `Balance`, ...) with lenient parsing and the full JSON kept on `.raw`.
+- Exception hierarchy rooted at `FastSaverError`: `ConfigurationError`, `APIError`
+  (`AuthenticationError`, `InsufficientCreditsError`, `RateLimitError`,
+  `InvalidRequestError`, `ValidationError`, `FetchError`, `NotFoundError`,
+  `ServerError`), `TransportError` (`RequestTimeoutError`) and `DownloadError`.
+- Automatic retries with exponential backoff and jitter for connection errors,
+  HTTP 5xx and HTTP 429 (honours `Retry-After`); read timeouts are never retried.
+- Per-endpoint default timeouts (long read timeouts for YouTube download and
+  Telegram audio) with per-call overrides.
+- Helpers: `detect_platform()`, `extract_youtube_id()`, `YOUTUBE_FORMATS`, `CREDIT_COSTS`.
+- `fastsaver` command-line interface (`fastsaver fetch`, `fastsaver youtube ...`,
+  `fastsaver shazam ...`, `fastsaver balance`, `fastsaver save`) with JSON output.
+- PEP 561 `py.typed` marker; Python 3.9–3.14 support; only dependency is `httpx`.
+
+[Unreleased]: https://github.com/coder2077/fastsaver/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/coder2077/fastsaver/releases/tag/v0.1.0

fastsaver-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to fastsaver
+
+Thanks for taking the time to contribute! This document explains how to set up a
+development environment, run the checks, and ship a release.
+
+## Development setup
+
+The project uses [uv](https://docs.astral.sh/uv/) for environment management and
+[hatchling](https://hatch.pypa.io/) as the build backend (src layout).
+
+```bash
+git clone https://github.com/coder2077/fastsaver.git
+cd fastsaver
+
+# Create .venv and install the package (editable) plus the "dev" dependency group
+uv sync
+
+# Run the checks
+.venv/bin/python -m pytest tests
+.venv/bin/ruff check src tests examples
+.venv/bin/ruff format --check src tests examples
+.venv/bin/mypy
+```
+
+`uv run <cmd>` works as well (for example `uv run pytest`). To test against a
+specific interpreter use `uv sync --python 3.9` (the package supports 3.9–3.14).
+
+Auto-format before committing:
+
+```bash
+.venv/bin/ruff format src tests examples
+.venv/bin/ruff check --fix src tests examples
+```
+
+## Running the live tests
+
+The regular test-suite is fully mocked with `respx` and needs no network access.
+`tests/test_live.py` talks to the real API and is skipped unless **both** of the
+following environment variables are set:
+
+```bash
+export FASTSAVER_API_KEY="fs_sk_..."   # your own key from https://api.fastsaver.io
+export FASTSAVER_LIVE=1
+.venv/bin/python -m pytest tests/test_live.py
+```
+
+Live tests call `balance()` (free) and perform a single `fetch()`, which costs a
+couple of credits. Never paste a real key into source code, fixtures or CI logs —
+tests use fake keys such as `fs_sk_test_...`.
+
+## Pull request guidelines
+
+- Open an issue first for larger changes so we can agree on the design.
+- Keep pull requests focused; one topic per PR.
+- Add or update tests for every behaviour change (sync **and** async where applicable).
+- Make sure `pytest`, `ruff check`, `ruff format --check` and `mypy` all pass locally;
+  CI runs the same commands on Python 3.9–3.14.
+- Keep the public API in sync between `FastSaver` and `AsyncFastSaver`.
+- Models must parse leniently (missing keys -> `None`/empty, unknown keys ignored).
+- Code comments, docstrings and docs are written in English.
+- Update `CHANGELOG.md` under the `[Unreleased]` heading.
+- Use `from __future__ import annotations` and Python 3.9 compatible syntax.
+
+## Release process
+
+1. Bump the version in `src/fastsaver/_version.py`.
+2. Move the `[Unreleased]` entries in `CHANGELOG.md` under a new
+   `## [X.Y.Z] - YYYY-MM-DD` heading and update the comparison links at the bottom.
+3. Commit and push to `main`, then tag and push the tag:
+
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+
+4. Create a GitHub Release from the `vX.Y.Z` tag (copy the changelog entry into the
+   release notes). Publishing the release triggers `.github/workflows/publish.yml`,
+   which builds the sdist/wheel with `uv build`, verifies them with `twine check` and
+   uploads them to PyPI using **Trusted Publishing** (OIDC) — no API token is stored
+   in the repository.
+
+### One-time PyPI Trusted Publisher setup
+
+Trusted Publishing has to be configured once on PyPI so that GitHub Actions is
+allowed to upload the `fastsaver` project:
+
+1. Log in to https://pypi.org and open the project page for `fastsaver`
+   (for the very first release use https://pypi.org/manage/account/publishing/ and
+   add a *pending* publisher — the project is created on the first upload).
+2. Under **Publishing** -> **Add a new publisher** choose **GitHub** and fill in:
+   - Owner: `coder2077`
+   - Repository name: `fastsaver`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi`
+3. In the GitHub repository go to **Settings -> Environments**, create an
+   environment called `pypi` and (recommended) add required reviewers so a human
+   approves every upload.
+
+The workflow requests `id-token: write` permission, which is all
+`pypa/gh-action-pypi-publish` needs to exchange the GitHub OIDC token for a
+short-lived PyPI upload token.
+
+## Code of conduct
+
+Be kind and constructive. Harassment or disrespectful behaviour is not tolerated.
+
+## Questions?
+
+Open a GitHub Discussion/Issue, join the Telegram channel https://t.me/fastsaverapi
+or e-mail support@fastsaver.io.

fastsaver-0.1.0/LICENSE

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