radimbig-pinchana-core 1.0.0

Unofficial PyPI distribution of Pinchana Core maintained by radimbig

📦 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.

• 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

pip install radimbig-pinchana-core

Import in Python

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.