Metadata-Version: 2.4
Name: radimbig-pinchana-core
Version: 1.0.0
Summary: Unofficial PyPI distribution of Pinchana Core maintained by radimbig
Keywords: pinchana,scraping,media,shared-library,fork,unofficial
Author: Pinchana
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: fastapi>=0.136.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: pydantic>=2.13.3
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: tenacity>=9.1.4
Requires-Dist: yt-dlp>=2026.3.17
Maintainer: radimbig
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/radimbig/pinchana-core
Project-URL: Repository, https://github.com/radimbig/pinchana-core
Project-URL: Issues, https://github.com/radimbig/pinchana-core/issues
Project-URL: Upstream, https://github.com/Pinchana/pinchana-core
Description-Content-Type: text/markdown

# 📦 Radimbig Pinchana Core

**Radimbig Pinchana Core** is an unofficial PyPI distribution of the original Pinchana Core project, maintained by `radimbig`.

This fork exists to provide an installable package for downstream consumers. It is not an official upstream release by the original Pinchana author.

The Python import name remains `pinchana_core`.

- Fork package name on PyPI: `radimbig-pinchana-core`
- Python import name: `pinchana_core`
- Upstream project: https://github.com/Pinchana/pinchana-core

It provides shared models, storage management, VPN control, and Docker orchestration logic used by both the gateway and the individual scraper modules.

---

## ✨ Key Components

### 1. Models (`pinchana_core.models`)
Defines the standard Pydantic v2 schemas for requests and responses, ensuring consistent data structures across all modules.
- `ScrapeRequest`: Standardizes input URL and options.
- `ScrapeResponse`: Uniform output format for media metadata.
- `MediaItem`: Represents an individual image or video in a gallery.

### 2. Storage (`pinchana_core.storage`)
An intelligent file-based storage system with a **Global Media Cache**.
- **LRU Eviction:** Automatically deletes the oldest media files when the cache exceeds a configurable size (e.g., 10GB).
- **Download Helpers:** Concurrent downloading of media with retry logic.
- **Path Resolution:** Standardized directory structure for cached media.

### 3. VPN Controller (`pinchana_core.vpn`)
Provides an interface to interact with [Gluetun](https://github.com/qdm12/gluetun).
- **Signal Rotation:** Triggers an immediate IP change via the Gluetun API.
- **Health Checks:** Monitors the status of the VPN tunnel.

### 4. Docker Manager (`pinchana_core.docker_manager`)
Handles the discovery and lifecycle of scraper modules running in Docker containers.
- **Dynamic Discovery:** Reads `modules.yaml` to identify available scrapers and their route patterns.
- **Lifecycle Control:** Can programmatically start, stop, or rebuild scraper containers.

### 5. Plugin Registry (`pinchana_core.plugins`)
A lightweight registry for "in-process" plugins, allowing modules to be imported directly into the server for easier development or single-binary deployments.

---

## 🛠 Usage

This package is intended to be used as a dependency in Pinchana-based projects that need a PyPI-installable distribution.

### Install from PyPI
```bash
pip install radimbig-pinchana-core
```

### Import in Python
```bash
python -c "import pinchana_core; print(pinchana_core.__all__)"
```

## 🚀 Release Flow

This fork is prepared for tag-based PyPI publishing through GitHub Actions.

To publish a new release, the maintainer only needs to:

1. Add `PYPI_API_TOKEN` to the GitHub repository secrets.
2. Create and push a release tag matching the package version, for example `v1.0.0`.

The GitHub Actions publish workflow will build the package and upload it to PyPI.

### Required GitHub Secret

- `PYPI_API_TOKEN`: PyPI API token for the `radimbig-pinchana-core` project.

## Upstream Attribution

This repository contains an MIT-licensed fork of the original Pinchana Core project.

- Original project: https://github.com/Pinchana/pinchana-core
- Original author and upstream decisions remain with the upstream project
- This fork only maintains packaging and distribution under the `radimbig` namespace

---

## 📜 License

MIT. See the LICENSE file for details.
