imagescv 0.1.0__tar.gz

imagescv-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 images.cv
+
+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.
+
+The license above covers this library's code only. Each dataset on images.cv
+has its own license; see imagescv.info("<name>")["license"].

imagescv-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: imagescv
+Version: 0.1.0
+Summary: Download labeled image datasets in one line of Python.
+Author: images.cv
+License-Expression: MIT
+Project-URL: Homepage, https://images.cv
+Project-URL: Documentation, https://images.cv/dashboard/api-keys
+Project-URL: Source, https://github.com/images-cv/imagescv
+Project-URL: Issues, https://github.com/images-cv/imagescv/issues
+Keywords: dataset,images,computer-vision,machine-learning,image-classification,images.cv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: tqdm>=4.60
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Requires-Dist: torchvision; extra == "torch"
+Dynamic: license-file
+
+# imagescv
+
+Download [images.cv](https://images.cv) datasets in one line.
+
+```
+pip install imagescv
+```
+
+Free. Create an API key at <https://images.cv/dashboard/api-keys> (up to 25 dataset downloads per
+day per account).
+
+```python
+import imagescv
+imagescv.login("icv_...")                 # or set IMAGESCV_API_KEY
+
+imagescv.search("firetruck")              # [{"name": "firetruck", "images": 562, ...}]
+imagescv.info("firetruck")                # dataset card: images, classes, license, sources
+
+ds = imagescv.load(
+    "firetruck",
+    size="size_128",                      # nochange, size_16, size_32, size_64, size_128, size_256
+    color="gray",                         # color or gray
+    augmentations=["rotate", "hflip"],    # see imagescv.AUGMENTATIONS
+    augmentation_percent=30,              # share of images augmented
+    split=(0.7, 0.2, 0.1),                # train / val / test
+    download_path="data",                 # optional; default is the current folder
+)
+print(ds)                                 # images, classes, splits
+train = ds.to_torch("train")              # needs: pip install imagescv[torch]
+```
+
+Datasets download into the current directory, in a folder like
+`firetruck_size_128_color_70-20/` that contains `data/train|val|test/<class>/` and
+`meta.json` (also available as `ds.meta`). Pass `download_path="D:/data"` to choose another
+folder. Asking again for the same options reuses the folder instead of downloading again
+(`force=True` re-downloads).
+Dataset licenses vary; `info()["license"]` is "Unknown" when a source has none on file.

imagescv-0.1.0/README.md

@@ -0,0 +1,37 @@
+# imagescv
+
+Download [images.cv](https://images.cv) datasets in one line.
+
+```
+pip install imagescv
+```
+
+Free. Create an API key at <https://images.cv/dashboard/api-keys> (up to 25 dataset downloads per
+day per account).
+
+```python
+import imagescv
+imagescv.login("icv_...")                 # or set IMAGESCV_API_KEY
+
+imagescv.search("firetruck")              # [{"name": "firetruck", "images": 562, ...}]
+imagescv.info("firetruck")                # dataset card: images, classes, license, sources
+
+ds = imagescv.load(
+    "firetruck",
+    size="size_128",                      # nochange, size_16, size_32, size_64, size_128, size_256
+    color="gray",                         # color or gray
+    augmentations=["rotate", "hflip"],    # see imagescv.AUGMENTATIONS
+    augmentation_percent=30,              # share of images augmented
+    split=(0.7, 0.2, 0.1),                # train / val / test
+    download_path="data",                 # optional; default is the current folder
+)
+print(ds)                                 # images, classes, splits
+train = ds.to_torch("train")              # needs: pip install imagescv[torch]
+```
+
+Datasets download into the current directory, in a folder like
+`firetruck_size_128_color_70-20/` that contains `data/train|val|test/<class>/` and
+`meta.json` (also available as `ds.meta`). Pass `download_path="D:/data"` to choose another
+folder. Asking again for the same options reuses the folder instead of downloading again
+(`force=True` re-downloads).
+Dataset licenses vary; `info()["license"]` is "Unknown" when a source has none on file.

imagescv-0.1.0/imagescv/__init__.py

@@ -0,0 +1,12 @@
+"""images.cv datasets in one line:
+
+    import imagescv
+    imagescv.login("icv_...")          # or set IMAGESCV_API_KEY
+    ds = imagescv.load("firetruck")
+    print(ds.classes, ds.root)
+"""
+from ._version import __version__
+from .client import login, info, load, search, SIZES, COLORS, AUGMENTATIONS
+from .dataset import Dataset
+
+__all__ = ["__version__", "login", "info", "load", "search", "Dataset", "SIZES", "COLORS", "AUGMENTATIONS"]

imagescv-0.1.0/imagescv/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

imagescv-0.1.0/imagescv/client.py

@@ -0,0 +1,284 @@
+import os
+import secrets
+import shutil
+import time
+import zipfile
+from pathlib import Path
+
+import requests
+from tqdm.auto import tqdm
+
+from ._version import __version__
+from .dataset import Dataset
+
+API_BASE_URL = os.environ.get("IMAGESCV_API_URL", "https://api.images.cv")
+
+# The API sits behind Cloudflare, which blocks the default python-requests
+# User-Agent. Same headers the Colab starter notebook uses.
+_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+    # Identifies the library honestly. The word "python" is avoided on purpose:
+    # the site's Cloudflare rule "Block Data Scraping Bots" blocks it.
+    "User-Agent": f"imagescv/{__version__} (+https://images.cv)",
+}
+
+_api_key = None
+
+
+def login(api_key):
+    """Set the API key for this session (otherwise IMAGESCV_API_KEY is used)."""
+    global _api_key
+    _api_key = api_key
+
+
+KEYS_URL = "https://images.cv/dashboard/api-keys"
+
+
+def _headers():
+    key = _api_key or os.environ.get("IMAGESCV_API_KEY")
+    if not key:
+        raise RuntimeError(
+            f"No API key. Create a free one at {KEYS_URL}, then call imagescv.login('icv_...') "
+            "or set the IMAGESCV_API_KEY environment variable.")
+    h = dict(_HEADERS)
+    h["X-API-Key"] = key
+    return h
+
+
+def _post(path, body, timeout=45, retries=2):
+    resp = None
+    for attempt in range(retries + 1):
+        try:
+            resp = requests.post(API_BASE_URL + path, json=body, headers=_headers(), timeout=timeout)
+            break
+        except requests.exceptions.RequestException as exc:
+            if attempt == retries:
+                raise RuntimeError(f"Network error calling {path}: {exc}") from exc
+            time.sleep(2 * (attempt + 1))
+    if "application/json" not in resp.headers.get("Content-Type", ""):
+        raise RuntimeError(
+            f"{path} returned non-JSON ({resp.status_code}); the request was probably "
+            f"blocked before reaching the API. First bytes: {resp.text[:120]!r}")
+    data = resp.json()
+    if resp.status_code == 401:
+        raise RuntimeError(f"API key rejected (invalid or revoked). Check or create one at {KEYS_URL}")
+    if resp.status_code == 429:
+        raise RuntimeError("Rate limited: " + str(data.get("error", "too many requests")))
+    if resp.status_code != 200 or data.get("isError"):
+        raise RuntimeError(f"{path} failed ({resp.status_code}): {data}")
+    return data
+
+
+SIZES = ("nochange", "size_16", "size_32", "size_64", "size_128", "size_256")
+COLORS = ("color", "gray")
+AUGMENTATIONS = (
+    "rotate", "hflip", "vflip", "crop", "change_aspect_ratio", "perspective",
+    "edge_enhance", "max_filter", "min_filter", "sharpen", "smooth", "blur",
+    "brightness", "contrast", "saturation", "color_jitter", "shuffle_pixels",
+    "random_noise", "cutout", "jpeg_compression",
+)
+
+# Same spellings the website resolves (stored value -> name, url).
+_LICENSES = {
+    "cc": ("CC0: Public Domain", "https://creativecommons.org/publicdomain/zero/1.0/"),
+    "cc1": ("Database: Open Database, Contents: Database Contents", "https://opendatacommons.org/licenses/odbl/1-0/"),
+    "cc2": ("CC BY 4.0", "https://creativecommons.org/licenses/by/4.0/"),
+    "cc3": ("(c) Original Authors", None),
+    "nn": ("GPL 2", "http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"),
+    "nn1": ("GNU Lesser General Public License 3.0", "http://www.gnu.org/licenses/lgpl-3.0.html"),
+    "nn2": ("CC BY-NC-ND 4.0", "https://creativecommons.org/licenses/by-nc-nd/4.0/"),
+    "nn3": ("Academic Research (c) Original Authors", None),
+}
+_LICENSE_ALIASES = {"cc0": "cc", "nn0": "nn"}
+
+
+def _resolve_license(value):
+    raw = (value or "").strip().lower()
+    return _LICENSES.get(_LICENSE_ALIASES.get(raw, raw))
+
+
+def info(name):
+    """The dataset card: image count, classes, sources and license.
+
+    license is the shared license name when every source agrees, "Mixed" when
+    sources have different known licenses, and "Unknown" when a source has none
+    on file (always check the source before use).
+    """
+    d = _post("/get_items_image_category", {"category": name, "start_after": 0})["data"]
+    sources = []
+    for raw in d.get("dataSource") or []:
+        clean = raw[:-1] if raw.endswith("_") else raw
+        slug = clean.strip().lower().replace("_", "-").replace(" ", "-")
+        entry = {"name": clean.replace("_", " ").title(), "link": None, "license": None, "license_url": None}
+        try:
+            rows = _post("/get_data_sources", {"key": slug}).get("data") or []
+        except RuntimeError:
+            rows = []
+        if rows:
+            lic = _resolve_license(rows[0].get("license_type"))
+            entry.update(name=(rows[0].get("name") or clean).replace("_", " ").title(),
+                         link=rows[0].get("link") or None)
+            if lic:
+                entry.update(license=lic[0], license_url=lic[1])
+        sources.append(entry)
+
+    names = {s["license"] for s in sources}
+    if sources and None not in names:
+        license_text = names.pop() if len(names) == 1 else "Mixed"
+    else:
+        license_text = "Unknown"
+    classes = d.get("mainCategory") or []
+    return {
+        "name": name,
+        "images": d.get("sumCounter") or 0,
+        "classes": len(classes),
+        "class_names": classes,
+        "license": license_text,
+        "sources": sources,
+        "premium": bool(d.get("is_premium")),
+    }
+
+
+def search(query, min_images=-1, limit=50):
+    """Find datasets whose name starts with, or whose category contains, the query.
+
+    Returns a list of dicts: name (use it with load()), images, parent.
+    Uses the same two lookups as the website search: the category and its
+    sub-categories (with image counts), plus name-prefix suggestions.
+    """
+    q = (query or "").strip()
+    if not q:
+        return []
+    found = {}
+    for it in _post("/api/search_advanced", {"q": q, "minImages": min_images}).get("data") or []:
+        found[it["data_key"]] = {"name": it["data_key"], "images": it.get("count", 0),
+                                 "parent": it.get("parent")}
+    try:
+        resp = requests.get(API_BASE_URL + "/api/autocomplete", params={"q": q},
+                            headers=_headers(), timeout=45)
+        suggestions = resp.json().get("data") or []
+    except (requests.exceptions.RequestException, ValueError):
+        suggestions = []
+    for s in suggestions:
+        key = s.get("main_category") if isinstance(s, dict) else None
+        if key and key not in found:
+            found[key] = {"name": key, "images": None, "parent": s.get("parent")}
+    rows = sorted(found.values(), key=lambda r: (-(r["images"] or 0), r["name"]))
+    return rows[:limit]
+
+
+def _wait_for_url(link_id, timeout, poll=3.0):
+    deadline = time.monotonic() + timeout
+    with tqdm(total=timeout, unit="s", desc="Preparing package") as bar:
+        while time.monotonic() < deadline:
+            url = _post("/get_link", {"link_id": link_id})["data"].get("public_url") or ""
+            if url:
+                bar.n = bar.total
+                bar.refresh()
+                return url
+            time.sleep(poll)
+            bar.update(poll)
+    raise RuntimeError(
+        f"Package was not ready after {timeout}s (job id {link_id}). Large datasets can take "
+        f"longer: try load(..., timeout=1800), or start with a smaller dataset.")
+
+
+def _stream(url, dest):
+    resp = requests.get(url, stream=True, timeout=60,
+                        headers={"User-Agent": _HEADERS["User-Agent"]})
+    if resp.status_code != 200 or "html" in resp.headers.get("Content-Type", "").lower():
+        raise RuntimeError(f"Download failed ({resp.status_code})")
+    total = int(resp.headers.get("Content-Length", 0)) or None
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with open(dest, "wb") as fh, tqdm(total=total, unit="B", unit_scale=True, desc="Downloading") as bar:
+        for chunk in resp.iter_content(1024 * 1024):
+            fh.write(chunk)
+            bar.update(len(chunk))
+    with open(dest, "rb") as fh:
+        if fh.read(2) != b"PK":
+            dest.unlink()
+            raise RuntimeError("Downloaded file is not a ZIP")
+
+
+def _safe_extract(zip_path, target):
+    target = Path(target).resolve()
+    with zipfile.ZipFile(zip_path) as z:
+        for member in z.namelist():
+            if not str((target / member).resolve()).startswith(str(target)):
+                raise RuntimeError("Unsafe path in ZIP: " + member)
+        z.extractall(target)
+
+
+def load(name, size="size_128", color="color", augmentations=None,
+         augmentation_percent=30, split=(0.7, 0.2, 0.1), download_path=None,
+         force=False, timeout=1800):
+    """Download (or reuse the cached copy of) a dataset and return a Dataset.
+
+    size: one of SIZES ("nochange", "size_16" ... "size_256").
+    color: "color" or "gray".
+    augmentations: names from AUGMENTATIONS, e.g. ["rotate", "hflip", "blur"].
+        Each image gets one random augmentation from your list;
+        augmentation_percent (0-100) is the share of images augmented.
+    split: train/val/test fractions.
+    download_path: folder to download into (default: the current directory).
+        The dataset goes in <download_path>/<name>_<options>/, and asking for
+        the same options again reuses it instead of downloading again.
+    """
+    if size not in SIZES:
+        raise ValueError(f"size must be one of {SIZES}")
+    if color not in COLORS:
+        raise ValueError(f"color must be one of {COLORS}")
+    augs = sorted(set(augmentations or []))
+    bad = [a for a in augs if a not in AUGMENTATIONS]
+    if bad:
+        raise ValueError(f"unknown augmentations {bad}; valid: {AUGMENTATIONS}")
+    if not 0 <= augmentation_percent <= 100:
+        raise ValueError("augmentation_percent must be between 0 and 100")
+    if len(split) != 3 or abs(sum(split) - 1.0) > 0.01:
+        raise ValueError("split must be three fractions that sum to 1, e.g. (0.7, 0.2, 0.1)")
+
+    slug = "".join(c if c.isalnum() or c in "-_." else "_" for c in name)
+    variant = f"{size}_{color}_{int(round(split[0] * 100))}-{int(round(split[1] * 100))}"
+    if augs:
+        variant += "_" + "-".join(augs) + f"_p{int(augmentation_percent)}"
+    root = Path(download_path) if download_path else Path.cwd()
+    folder = root / f"{slug}_{variant}"
+    package = folder  # data/ and meta.json sit directly in this folder
+    marker = folder / ".complete"
+
+    if marker.exists() and not force:
+        return Dataset(name, package)
+
+    body = {
+        "output_size": size, "color_type": color, "images": [],
+        "categories": [name], "augmentations": [{"name": a, "checked": True} for a in augs],
+        "split_set": list(split),
+        "link_id": secrets.token_hex(20), "request_type": "CALL_FROM_SEARCH",
+        "user_email": [], "user_id": "", "augmentation_percent": int(augmentation_percent),
+    }
+    link_id = _post("/download_images", body)["data"].get("link_id")
+    if not link_id:
+        raise RuntimeError("The server did not accept the download job")
+    url = _wait_for_url(link_id, timeout)
+    zip_path = folder / "package.zip"
+    _stream(url, zip_path)
+    staging = folder / ".extract"
+    if staging.exists():
+        shutil.rmtree(staging)
+    _safe_extract(zip_path, staging)
+    # The server wraps everything in one images.cv_<id>/ folder; drop that
+    # wrapper so you get <folder>/data/train/... and <folder>/meta.json.
+    entries = list(staging.iterdir())
+    source = entries[0] if len(entries) == 1 and entries[0].is_dir() else staging
+    for item in source.iterdir():
+        target = folder / item.name
+        if target.is_dir():
+            shutil.rmtree(target)
+        elif target.exists():
+            target.unlink()
+        shutil.move(str(item), str(target))
+    shutil.rmtree(staging)
+    zip_path.unlink()
+    marker.write_text("ok")
+    return Dataset(name, package)

imagescv-0.1.0/imagescv/dataset.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+_IMG = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+
+
+def _find_split_root(package):
+    """The ZIP may nest the splits (e.g. data/train); find the folder that holds train/."""
+    package = Path(package)
+    for p in [package, *sorted(package.rglob("*"))]:
+        if p.is_dir() and (p / "train").is_dir():
+            return p
+    return package
+
+
+class Dataset:
+    def __init__(self, name, package):
+        self.name = name
+        self.package = Path(package)
+        self.root = _find_split_root(self.package)
+
+    @property
+    def meta(self):
+        """The package's meta.json (counts, split, size, color, augmentation), or {}."""
+        path = self.package / "meta.json"
+        if not path.exists():
+            return {}
+        import json
+        return json.loads(path.read_text(encoding="utf8"))
+
+    @property
+    def splits(self):
+        return sorted(d.name for d in self.root.iterdir() if d.is_dir())
+
+    @property
+    def classes(self):
+        train = self.root / "train"
+        base = train if train.is_dir() else self.root
+        return sorted(d.name for d in base.iterdir() if d.is_dir())
+
+    def paths(self, split="train"):
+        base = self.root / split
+        return sorted(p for p in base.rglob("*") if p.suffix.lower() in _IMG)
+
+    def __len__(self):
+        return sum(len(self.paths(s)) for s in self.splits)
+
+    def to_torch(self, split="train", transform=None):
+        try:
+            from torchvision import datasets
+        except ImportError as exc:
+            raise ImportError("Install with: pip install imagescv[torch]") from exc
+        return datasets.ImageFolder(str(self.root / split), transform=transform)
+
+    def __repr__(self):
+        return f"Dataset({self.name!r}, {len(self)} images, {len(self.classes)} classes, splits={self.splits})"

imagescv-0.1.0/imagescv.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: imagescv
+Version: 0.1.0
+Summary: Download labeled image datasets in one line of Python.
+Author: images.cv
+License-Expression: MIT
+Project-URL: Homepage, https://images.cv
+Project-URL: Documentation, https://images.cv/dashboard/api-keys
+Project-URL: Source, https://github.com/images-cv/imagescv
+Project-URL: Issues, https://github.com/images-cv/imagescv/issues
+Keywords: dataset,images,computer-vision,machine-learning,image-classification,images.cv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: tqdm>=4.60
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Requires-Dist: torchvision; extra == "torch"
+Dynamic: license-file
+
+# imagescv
+
+Download [images.cv](https://images.cv) datasets in one line.
+
+```
+pip install imagescv
+```
+
+Free. Create an API key at <https://images.cv/dashboard/api-keys> (up to 25 dataset downloads per
+day per account).
+
+```python
+import imagescv
+imagescv.login("icv_...")                 # or set IMAGESCV_API_KEY
+
+imagescv.search("firetruck")              # [{"name": "firetruck", "images": 562, ...}]
+imagescv.info("firetruck")                # dataset card: images, classes, license, sources
+
+ds = imagescv.load(
+    "firetruck",
+    size="size_128",                      # nochange, size_16, size_32, size_64, size_128, size_256
+    color="gray",                         # color or gray
+    augmentations=["rotate", "hflip"],    # see imagescv.AUGMENTATIONS
+    augmentation_percent=30,              # share of images augmented
+    split=(0.7, 0.2, 0.1),                # train / val / test
+    download_path="data",                 # optional; default is the current folder
+)
+print(ds)                                 # images, classes, splits
+train = ds.to_torch("train")              # needs: pip install imagescv[torch]
+```
+
+Datasets download into the current directory, in a folder like
+`firetruck_size_128_color_70-20/` that contains `data/train|val|test/<class>/` and
+`meta.json` (also available as `ds.meta`). Pass `download_path="D:/data"` to choose another
+folder. Asking again for the same options reuses the folder instead of downloading again
+(`force=True` re-downloads).
+Dataset licenses vary; `info()["license"]` is "Unknown" when a source has none on file.

imagescv-0.1.0/imagescv.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+imagescv/__init__.py
+imagescv/_version.py
+imagescv/client.py
+imagescv/dataset.py
+imagescv.egg-info/PKG-INFO
+imagescv.egg-info/SOURCES.txt
+imagescv.egg-info/dependency_links.txt
+imagescv.egg-info/requires.txt
+imagescv.egg-info/top_level.txt
+tests/test_api_key.py
+tests/test_dataset.py
+tests/test_load_options.py
+tests/test_search.py

imagescv-0.1.0/imagescv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

imagescv-0.1.0/imagescv.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.28
+tqdm>=4.60
+
+[torch]
+torch
+torchvision

imagescv-0.1.0/imagescv.egg-info/top_level.txt

@@ -0,0 +1 @@
+imagescv

imagescv-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "imagescv"
+dynamic = ["version"]
+description = "Download labeled image datasets in one line of Python."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "images.cv" }]
+keywords = ["dataset", "images", "computer-vision", "machine-learning", "image-classification", "images.cv"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = ["requests>=2.28", "tqdm>=4.60"]
+
+[project.optional-dependencies]
+torch = ["torch", "torchvision"]
+
+[project.urls]
+Homepage = "https://images.cv"
+Documentation = "https://images.cv/dashboard/api-keys"
+Source = "https://github.com/images-cv/imagescv"
+Issues = "https://github.com/images-cv/imagescv/issues"
+
+[tool.setuptools]
+packages = ["imagescv"]
+
+[tool.setuptools.dynamic]
+version = { attr = "imagescv._version.__version__" }

imagescv-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

imagescv-0.1.0/tests/test_api_key.py

@@ -0,0 +1,43 @@
+import pytest
+
+import imagescv
+from imagescv import client
+
+
+class _Resp:
+    def __init__(self, status, payload):
+        self.status_code = status
+        self._payload = payload
+        self.headers = {"Content-Type": "application/json"}
+        self.text = ""
+
+    def json(self):
+        return self._payload
+
+
+def test_key_is_sent_in_x_api_key_header():
+    assert client._headers()["X-API-Key"] == "icv_test"
+    imagescv.login("icv_mine")
+    assert client._headers()["X-API-Key"] == "icv_mine"
+    assert "Authorization" not in client._headers()
+
+
+def test_missing_key_gives_clear_error(monkeypatch):
+    monkeypatch.delenv("IMAGESCV_API_KEY")
+    with pytest.raises(RuntimeError, match="No API key"):
+        client._headers()
+
+
+def test_rejected_key_and_daily_limit_messages(monkeypatch):
+    monkeypatch.setattr(client.requests, "post", lambda *a, **k: _Resp(401, {"error": "x"}))
+    with pytest.raises(RuntimeError, match="API key rejected"):
+        client._post("/get_link", {})
+    monkeypatch.setattr(client.requests, "post", lambda *a, **k: _Resp(429, {"error": "Daily download limit reached (25 per user)"}))
+    with pytest.raises(RuntimeError, match="Daily download limit"):
+        client._post("/download_images", {})
+
+
+def test_user_agent_starts_with_imagescv_and_carries_the_version():
+    # The server's key gate matches on the "imagescv/" prefix.
+    assert client._HEADERS["User-Agent"].startswith("imagescv/")
+    assert imagescv.__version__ in client._HEADERS["User-Agent"]

imagescv-0.1.0/tests/test_dataset.py

@@ -0,0 +1,13 @@
+from imagescv.dataset import Dataset
+
+
+def test_nested_split_layout(tmp_path):
+    for split in ("train", "val"):
+        for cls in ("a", "b"):
+            d = tmp_path / "data" / split / cls
+            d.mkdir(parents=True)
+            (d / "1.png").write_bytes(b"x")
+    ds = Dataset("t", tmp_path)
+    assert ds.classes == ["a", "b"]
+    assert ds.splits == ["train", "val"]
+    assert len(ds) == 4

imagescv-0.1.0/tests/test_load_options.py

@@ -0,0 +1,103 @@
+import pytest
+
+import imagescv
+from imagescv import client
+
+
+def test_rejects_bad_options():
+    with pytest.raises(ValueError):
+        imagescv.load("cat", size="size_99")
+    with pytest.raises(ValueError):
+        imagescv.load("cat", color="sepia")
+    with pytest.raises(ValueError):
+        imagescv.load("cat", augmentations=["warp"])
+    with pytest.raises(ValueError):
+        imagescv.load("cat", augmentation_percent=150)
+    with pytest.raises(ValueError):
+        imagescv.load("cat", split=(0.9, 0.9, 0.9))
+
+
+def test_request_body_and_download_path(monkeypatch, tmp_path):
+    sent = {}
+
+    def fake_post(path, body, **k):
+        sent[path] = body
+        return {"data": {"link_id": "x"}}
+
+    monkeypatch.setattr(client, "_post", fake_post)
+    monkeypatch.setattr(client, "_wait_for_url", lambda *a, **k: "http://z")
+
+    def fake_stream(url, dest):
+        import zipfile
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(dest, "w") as z:
+            z.writestr("data/train/a/1.png", b"x")
+
+    monkeypatch.setattr(client, "_stream", fake_stream)
+    ds = imagescv.load("cat", size="size_64", color="gray", augmentations=["blur", "rotate"],
+                       augmentation_percent=40, download_path=tmp_path)
+    body = sent["/download_images"]
+    assert body["output_size"] == "size_64" and body["color_type"] == "gray"
+    assert body["augmentations"] == [{"name": "blur", "checked": True}, {"name": "rotate", "checked": True}]
+    assert body["augmentation_percent"] == 40
+    assert ds.package == tmp_path / "cat_size_64_gray_70-20_blur-rotate_p40"
+    assert ds.classes == ["a"]
+
+
+def test_default_download_path_is_cwd(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(client, "_post", lambda *a, **k: {"data": {"link_id": "x"}})
+    monkeypatch.setattr(client, "_wait_for_url", lambda *a, **k: "http://z")
+
+    def fake_stream(url, dest):
+        import zipfile
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(dest, "w") as z:
+            z.writestr("data/train/a/1.png", b"x")
+
+    monkeypatch.setattr(client, "_stream", fake_stream)
+    ds = imagescv.load("cat")
+    assert ds.package.parent == tmp_path
+
+
+def test_server_wrapper_folder_is_flattened(monkeypatch, tmp_path):
+    monkeypatch.setattr(client, "_post", lambda *a, **k: {"data": {"link_id": "x"}})
+    monkeypatch.setattr(client, "_wait_for_url", lambda *a, **k: "http://z")
+
+    def fake_stream(url, dest):
+        import zipfile
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(dest, "w") as z:
+            z.writestr("images.cv_abc/data/train/a/1.png", b"x")
+            z.writestr("images.cv_abc/meta.json", '{"amount_of_images": 1}')
+
+    monkeypatch.setattr(client, "_stream", fake_stream)
+    ds = imagescv.load("cat", download_path=tmp_path)
+    folder = tmp_path / "cat_size_128_color_70-20"
+    assert (folder / "data" / "train" / "a" / "1.png").exists()
+    assert (folder / "meta.json").exists()
+    assert not (folder / ".extract").exists()
+    assert ds.meta["amount_of_images"] == 1
+    assert ds.classes == ["a"]
+
+    # asking again reuses the folder, and force=True re-downloads cleanly
+    assert imagescv.load("cat", download_path=tmp_path).package == folder
+    imagescv.load("cat", download_path=tmp_path, force=True)
+    assert (folder / "data" / "train" / "a" / "1.png").exists()
+
+
+def test_info_license_logic(monkeypatch):
+    def fake_post(path, body, **k):
+        if path == "/get_items_image_category":
+            return {"data": {"sumCounter": 100, "mainCategory": ["a", "b"], "dataSource": ["kaggle_x", "other"]}}
+        key = body["key"]
+        return {"data": [{"name": key, "link": "http://l", "license_type": "cc0" if key == "kaggle-x" else "cc2"}]}
+
+    monkeypatch.setattr(client, "_post", fake_post)
+    card = imagescv.info("cat")
+    assert card["images"] == 100 and card["classes"] == 2
+    assert card["license"] == "Mixed"
+    monkeypatch.setattr(client, "_post", lambda p, b, **k: (
+        {"data": {"sumCounter": 1, "mainCategory": [], "dataSource": ["s"]}} if "items" in p
+        else {"data": [{"name": "s", "license_type": ""}]}))
+    assert imagescv.info("cat")["license"] == "Unknown"

imagescv-0.1.0/tests/test_search.py

@@ -0,0 +1,28 @@
+import imagescv
+from imagescv import client
+
+
+class _Resp:
+    def __init__(self, payload):
+        self._p = payload
+
+    def json(self):
+        return self._p
+
+
+def test_search_merges_and_sorts(monkeypatch):
+    monkeypatch.setattr(client, "_post", lambda path, body, **k: {"data": [
+        {"data_key": "traffic_cone", "count": 600, "parent": None},
+        {"data_key": "cone", "count": 40, "parent": "Shape"},
+    ]})
+    monkeypatch.setattr(client.requests, "get", lambda *a, **k: _Resp({"data": [
+        {"main_category": "cone", "parent": "Shape"},
+        {"main_category": "conehead", "parent": None},
+    ]}))
+    rows = imagescv.search("cone")
+    assert [r["name"] for r in rows] == ["traffic_cone", "cone", "conehead"]
+    assert rows[2]["images"] is None
+
+
+def test_search_empty_query():
+    assert imagescv.search("  ") == []