pyimagekit 0.1.0a2__tar.gz

pyimagekit-0.1.0a2/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*" # This catches both v0.1.0-test and v0.1.0
+
+jobs:
+  publish-test:
+    # Only runs if the tag contains "-test"
+    if: contains(github.ref_name, '-test')
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --index testpypi
+
+  publish-pypi:
+    # Only runs if the tag DOES NOT contain "-test"
+    if: startsWith(github.ref_name, 'v') && !contains(github.ref_name, '-test')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --index pypi

pyimagekit-0.1.0a2/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test
+tests/**/*.jpg
+tests/**/*.jpeg
+tests/**/text.txt
+
+# pypi
+.pypirc

pyimagekit-0.1.0a2/.python-version

@@ -0,0 +1 @@
+3.9

pyimagekit-0.1.0a2/LICENSE

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

pyimagekit-0.1.0a2/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: pyimagekit
+Version: 0.1.0a2
+Summary: A Python library that provides a unified interface for handling images across multiple formats and performing common image processing tasks.
+Project-URL: Repository, https://github.com/Hoopoes/pyimagekit
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21.6
+Requires-Dist: opencv-python-headless>=4.13.0.92
+Requires-Dist: pillow>=9.5.0
+Requires-Dist: pydantic>=2.5.3
+Provides-Extra: all
+Requires-Dist: pytesseract; extra == 'all'
+Provides-Extra: pytesseract
+Requires-Dist: pytesseract>=0.3.13; extra == 'pytesseract'
+Description-Content-Type: text/markdown
+
+# PyImageKit
+
+A Python library providing a unified interface for handling images across multiple formats (`bytes`, OpenCV `cv2`, Pillow `Image`) and performing common image processing tasks.
+
+## Installation
+
+```bash
+pip install pyimagekit
+```
+
+To include OCR support for document uprighting, install with the optional dependency:
+
+```bash
+pip install "pyimagekit[pytesseract]"
+```
+
+## Quick Start
+
+`pyimagekit` centers around the `SmartImage` class, which allows you to seamlessly load, transform, and export images. It implements a fluent interface so operations can be chained.
+
+```python
+from pyimagekit import SmartImage
+
+# 1. Load an image
+with open("document.jpg", "rb") as f:
+    img = SmartImage.from_bytes(f.read())
+
+# Alternatively:
+# img = SmartImage.from_cv2(cv2_image)
+# img = SmartImage.from_pillow(pil_image)
+
+# 2. Process the image
+processed_img = (
+    img.resize(width=800)
+       .rotate(90)
+       .ensure_document_portrait()
+)
+
+# 3. Export the processed image
+jpeg_bytes = processed_img.to_bytes(format="JPEG", quality=85)
+base64_str = processed_img.to_base64(format="PNG")
+cv2_mat = processed_img.to_cv2()
+pillow_img = processed_img.to_pillow()
+```
+
+## Features
+
+The `SmartImage` class currently supports the following operations:
+
+- **Loading:** `from_bytes`, `from_cv2`, `from_pillow`
+- **Exporting:** `to_cv2`, `to_pillow`, `to_bytes`, `to_base64`
+- **Transformations:** `resize`, `crop`, `rotate`, `sharpen_v1`, `sharpen_v2`, `adjust_quality`, `apply` (for custom functions)
+- **Document Processing:** `unwarp_document`, `ensure_document_upright`, `ensure_document_portrait`, `ensure_document_landscape`
+
+## License
+
+MIT License

pyimagekit-0.1.0a2/README.md

@@ -0,0 +1,57 @@
+# PyImageKit
+
+A Python library providing a unified interface for handling images across multiple formats (`bytes`, OpenCV `cv2`, Pillow `Image`) and performing common image processing tasks.
+
+## Installation
+
+```bash
+pip install pyimagekit
+```
+
+To include OCR support for document uprighting, install with the optional dependency:
+
+```bash
+pip install "pyimagekit[pytesseract]"
+```
+
+## Quick Start
+
+`pyimagekit` centers around the `SmartImage` class, which allows you to seamlessly load, transform, and export images. It implements a fluent interface so operations can be chained.
+
+```python
+from pyimagekit import SmartImage
+
+# 1. Load an image
+with open("document.jpg", "rb") as f:
+    img = SmartImage.from_bytes(f.read())
+
+# Alternatively:
+# img = SmartImage.from_cv2(cv2_image)
+# img = SmartImage.from_pillow(pil_image)
+
+# 2. Process the image
+processed_img = (
+    img.resize(width=800)
+       .rotate(90)
+       .ensure_document_portrait()
+)
+
+# 3. Export the processed image
+jpeg_bytes = processed_img.to_bytes(format="JPEG", quality=85)
+base64_str = processed_img.to_base64(format="PNG")
+cv2_mat = processed_img.to_cv2()
+pillow_img = processed_img.to_pillow()
+```
+
+## Features
+
+The `SmartImage` class currently supports the following operations:
+
+- **Loading:** `from_bytes`, `from_cv2`, `from_pillow`
+- **Exporting:** `to_cv2`, `to_pillow`, `to_bytes`, `to_base64`
+- **Transformations:** `resize`, `crop`, `rotate`, `sharpen_v1`, `sharpen_v2`, `adjust_quality`, `apply` (for custom functions)
+- **Document Processing:** `unwarp_document`, `ensure_document_upright`, `ensure_document_portrait`, `ensure_document_landscape`
+
+## License
+
+MIT License

pyimagekit-0.1.0a2/dev.md

@@ -0,0 +1,98 @@
+**To local install package while developing**
+(Install package)
+uv pip install .[dev] (Locally and also install the development dependencies)
+uv pip install -e .[dev] (In editable mode and also install the development dependencies)
+uv pip install -e .[dev,pytesseract] (In editable mode and also install the development and optional dependencies)
+
+**How to publish package using uv**
+
+[building-your-package](https://docs.astral.sh/uv/guides/package/#building-your-package)
+
+[packaging-projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+
+**Package stats**
+[PyPiStats](https://pypistats.org)
+
+**test**
+uv run --python 3.9 pytest
+uv run --python 3.10 pytest
+... so on
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Development & Release Workflow
+
+### 1. Testing (TestPyPI)
+Use this when you want to verify the package builds correctly and can be installed via pip.
+
+* **Version:** Update `version` in `pyproject.toml` to an alpha/beta (e.g., `0.1.0a1`).
+* **Branch:** `test`
+* **Commands:**
+    ```bash
+    # 1. Commit your changes
+    git add .
+    git commit -m "feat: <description of change>"
+
+    # 2. Create the test tag
+    git tag v0.0.1a1-test
+
+    # 3. Push the branch first (if code already pushed then no need)
+    git push origin test
+
+    # 4. Push the tag to GitHub
+    git push origin v0.0.1a1-test
+    ```
+    *Result: Automatically builds and publishes to [TestPyPI](https://test.pypi.org/).*
+
+---
+
+### 2. Official Release (PyPI)
+Use this only when the code is stable and ready for public use.
+
+* **Version:** Update `version` in `pyproject.toml` to a stable version (e.g., `0.1.0`).
+* **Branch:** `main` (Merge from `test` first).
+* **Commands:**
+    ```bash
+    # 1. Merge changes into main
+    git checkout main
+    git merge test
+    
+    # 2. Tag the version (Must match pyproject.toml)
+    git tag v0.1.0
+    
+    # 3. Push code and tags
+    git push origin main --tags
+    ```
+    *Result: Automatically builds and publishes to [PyPI](https://pypi.org/).*
+
+---
+
+### 3. Commit Message Standards
+We follow **Conventional Commits** to keep the history clean:
+
+| Prefix      | Use Case                    | Example                                  |
+| :---------- | :-------------------------- | :--------------------------------------- |
+| `feat:`     | A new feature               | `feat: add opencv-based blurring`        |
+| `fix:`      | A bug fix                   | `fix: resolve numpy overflow in scaling` |
+| `docs:`     | Documentation changes       | `docs: update dev.md with release flow`  |
+| `chore:`    | Maintenance/Version bump    | `chore: bump version to 0.1.0`           |
+| `refactor:` | Code cleanup (no new logic) | `refactor: simplify internal loop`       |
+
+---
+
+### Local Sanity Check
+Always run a local build before pushing to ensure `hatchling` (the build backend) is happy:
+```bash
+uv build
+```
+*Verify that the `.whl` and `.tar.gz` files appear in the `dist/` folder.*

pyimagekit-0.1.0a2/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyimagekit"
+version = "0.1.0a2"
+description = "A Python library that provides a unified interface for handling images across multiple formats and performing common image processing tasks."
+readme = "README.md"
+license = 'MIT'
+license-files = ['LICENSE']
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+    "Natural Language :: English",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.21.6",
+    "opencv-python-headless>=4.13.0.92",
+    "pillow>=9.5.0",
+    "pydantic>=2.5.3",
+]
+
+[project.optional-dependencies]
+pytesseract = ["pytesseract>=0.3.13"]
+all = ["pytesseract"]
+
+[dependency-groups]
+dev = ["pytest>=7.4.4"]
+
+[project.urls]
+Repository = "https://github.com/Hoopoes/pyimagekit"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple/"
+publish-url = "https://upload.pypi.org/legacy/"
+explicit = true

pyimagekit-0.1.0a2/src/pyimagekit/__init__.py

@@ -0,0 +1,17 @@
+from .smart_image import (
+    ImageFormat,
+    SmartImage,
+    ImageEmpty,
+    ImageTooLarge,
+    InvalidImage,
+    InvalidAngle,
+)
+
+__all__ = [
+    "ImageFormat",
+    "SmartImage",
+    "ImageEmpty",
+    "ImageTooLarge",
+    "InvalidImage",
+    "InvalidAngle",
+]