prozorro-cli 0.1.0__tar.gz

prozorro_cli-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 prozorro-cli contributors
+
+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.
+

prozorro_cli-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: prozorro-cli
+Version: 0.1.0
+Summary: Small command-line client for public Prozorro tender data
+Author: prozorro-cli contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/radimbig2/prozorro-cli
+Project-URL: Issues, https://github.com/radimbig2/prozorro-cli/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# prozorro-cli
+
+Невелика CLI для отримання публічних даних про тендери Prozorro за UA-ID,
+внутрішнім GUID, стандартним UUID або посиланням.
+
+## Встановлення
+
+```powershell
+pip install prozorro-cli
+prozorro-cli --help
+```
+
+Для ізольованого глобального встановлення CLI також можна використати
+`pipx install prozorro-cli`.
+
+## Команди
+
+```powershell
+# Посилання на повний JSON у Public API
+prozorro-cli tender UA-2026-06-15-003439-a --link
+
+# Посилання на HTML-сторінку тендера
+prozorro-cli tender UA-2026-06-15-003439-a --link-html
+
+# Надрукувати й відкрити JSON Public API у браузері
+prozorro-cli tender UA-2026-06-15-003439-a --link --open
+
+# Надрукувати й відкрити HTML-сторінку у браузері
+prozorro-cli tender UA-2026-06-15-003439-a --link-html --open
+
+# Скорочений alias для --link-html
+prozorro-cli tender UA-2026-06-15-003439-a --linkhtml --open
+
+# Внутрішній id Prozorro
+prozorro-cli tender UA-2026-06-15-003439-a --guid
+
+# Той самий id у стандартному форматі UUID
+prozorro-cli tender UA-2026-06-15-003439-a --guid-normal
+
+# Повний JSON із public-api.prozorro.gov.ua
+prozorro-cli tender UA-2026-06-15-003439-a
+
+# Повний JSON за GUID без дефісів
+prozorro-cli tender 5d2590ef8a1b455f8d09ceeae474b21f
+
+# Повний JSON за стандартним UUID
+prozorro-cli tender 5d2590ef-8a1b-455f-8d09-ceeae474b21f
+
+# Повний JSON за посиланням на сторінку тендера
+prozorro-cli tender https://prozorro.gov.ua/tender/UA-2026-06-15-003439-a
+
+# Повний JSON за посиланням Public API
+prozorro-cli tender https://public-api.prozorro.gov.ua/api/2.5/tenders/5d2590ef8a1b455f8d09ceeae474b21f
+
+# Завантажити всі файли з data.documents за посиланням Public API
+prozorro-cli documents https://public-api.prozorro.gov.ua/api/2.5/tenders/5d2590ef8a1b455f8d09ceeae474b21f --output /temp
+
+# Те саме за UA-ID
+prozorro-cli documents UA-2026-06-15-003439-a --output /temp
+```
+
+Для UA-ID і посилання на сторінку CLI спочатку отримує внутрішній `id` через
+публічний endpoint `https://prozorro.gov.ua/api/tenders/<UA-ID>/summary`.
+Для GUID, UUID і посилання Public API цей крок пропускається. Повний JSON
+завантажується з `https://public-api.prozorro.gov.ua/api/2.5/tenders/<id>`.
+
+Команда `documents` створює каталог із `--output`, якщо його ще немає, і
+завантажує туди всі файли з `data.documents`. Імена беруться з `title`;
+однакові імена не перезаписуються, а отримують суфікси `(2)`, `(3)` тощо.
+
+## Розробка
+
+```powershell
+$env:PYTHONPATH = "$PWD\src"
+python -m unittest discover -s tests -v
+python -m prozorro_cli tender UA-2026-06-15-003439-a --guid
+```
+
+## Реліз
+
+1. Оновіть `version` у `pyproject.toml` та `__version__` у
+   `src/prozorro_cli/__init__.py`.
+2. Створіть і опублікуйте GitHub Release з тегом тієї ж версії, наприклад
+   `v0.1.0`.
+3. GitHub Actions перевірить тести, збере wheel і sdist, додасть їх до Release
+   та опублікує пакет у PyPI.
+
+Для публікації потрібен GitHub Actions secret `PYPI_API_TOKEN` з API-токеном
+PyPI. Job публікації запускається в GitHub environment `pypi`.

prozorro_cli-0.1.0/README.md

@@ -0,0 +1,89 @@
+# prozorro-cli
+
+Невелика CLI для отримання публічних даних про тендери Prozorro за UA-ID,
+внутрішнім GUID, стандартним UUID або посиланням.
+
+## Встановлення
+
+```powershell
+pip install prozorro-cli
+prozorro-cli --help
+```
+
+Для ізольованого глобального встановлення CLI також можна використати
+`pipx install prozorro-cli`.
+
+## Команди
+
+```powershell
+# Посилання на повний JSON у Public API
+prozorro-cli tender UA-2026-06-15-003439-a --link
+
+# Посилання на HTML-сторінку тендера
+prozorro-cli tender UA-2026-06-15-003439-a --link-html
+
+# Надрукувати й відкрити JSON Public API у браузері
+prozorro-cli tender UA-2026-06-15-003439-a --link --open
+
+# Надрукувати й відкрити HTML-сторінку у браузері
+prozorro-cli tender UA-2026-06-15-003439-a --link-html --open
+
+# Скорочений alias для --link-html
+prozorro-cli tender UA-2026-06-15-003439-a --linkhtml --open
+
+# Внутрішній id Prozorro
+prozorro-cli tender UA-2026-06-15-003439-a --guid
+
+# Той самий id у стандартному форматі UUID
+prozorro-cli tender UA-2026-06-15-003439-a --guid-normal
+
+# Повний JSON із public-api.prozorro.gov.ua
+prozorro-cli tender UA-2026-06-15-003439-a
+
+# Повний JSON за GUID без дефісів
+prozorro-cli tender 5d2590ef8a1b455f8d09ceeae474b21f
+
+# Повний JSON за стандартним UUID
+prozorro-cli tender 5d2590ef-8a1b-455f-8d09-ceeae474b21f
+
+# Повний JSON за посиланням на сторінку тендера
+prozorro-cli tender https://prozorro.gov.ua/tender/UA-2026-06-15-003439-a
+
+# Повний JSON за посиланням Public API
+prozorro-cli tender https://public-api.prozorro.gov.ua/api/2.5/tenders/5d2590ef8a1b455f8d09ceeae474b21f
+
+# Завантажити всі файли з data.documents за посиланням Public API
+prozorro-cli documents https://public-api.prozorro.gov.ua/api/2.5/tenders/5d2590ef8a1b455f8d09ceeae474b21f --output /temp
+
+# Те саме за UA-ID
+prozorro-cli documents UA-2026-06-15-003439-a --output /temp
+```
+
+Для UA-ID і посилання на сторінку CLI спочатку отримує внутрішній `id` через
+публічний endpoint `https://prozorro.gov.ua/api/tenders/<UA-ID>/summary`.
+Для GUID, UUID і посилання Public API цей крок пропускається. Повний JSON
+завантажується з `https://public-api.prozorro.gov.ua/api/2.5/tenders/<id>`.
+
+Команда `documents` створює каталог із `--output`, якщо його ще немає, і
+завантажує туди всі файли з `data.documents`. Імена беруться з `title`;
+однакові імена не перезаписуються, а отримують суфікси `(2)`, `(3)` тощо.
+
+## Розробка
+
+```powershell
+$env:PYTHONPATH = "$PWD\src"
+python -m unittest discover -s tests -v
+python -m prozorro_cli tender UA-2026-06-15-003439-a --guid
+```
+
+## Реліз
+
+1. Оновіть `version` у `pyproject.toml` та `__version__` у
+   `src/prozorro_cli/__init__.py`.
+2. Створіть і опублікуйте GitHub Release з тегом тієї ж версії, наприклад
+   `v0.1.0`.
+3. GitHub Actions перевірить тести, збере wheel і sdist, додасть їх до Release
+   та опублікує пакет у PyPI.
+
+Для публікації потрібен GitHub Actions secret `PYPI_API_TOKEN` з API-токеном
+PyPI. Job публікації запускається в GitHub environment `pypi`.

prozorro_cli-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "prozorro-cli"
+version = "0.1.0"
+description = "Small command-line client for public Prozorro tender data"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "prozorro-cli contributors" }]
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Homepage = "https://github.com/radimbig2/prozorro-cli"
+Issues = "https://github.com/radimbig2/prozorro-cli/issues"
+
+[project.scripts]
+prozorro-cli = "prozorro_cli.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

prozorro_cli-0.1.0/setup.cfg

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

prozorro_cli-0.1.0/src/prozorro_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Command-line client for public Prozorro tender data."""
+
+__version__ = "0.1.0"
+

prozorro_cli-0.1.0/src/prozorro_cli/__main__.py

@@ -0,0 +1,6 @@
+from prozorro_cli.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

prozorro_cli-0.1.0/src/prozorro_cli/cli.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import webbrowser
+from collections.abc import Sequence
+
+from prozorro_cli.client import (
+    ProzorroError,
+    download_documents,
+    fetch_tender,
+    normal_guid,
+    public_api_link,
+    resolve_guid,
+    tender_link,
+)
+
+
+def configure_windows_streams() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8")
+
+
+def print_link(url: str, *, open_in_browser: bool) -> None:
+    print(url)
+    if open_in_browser and not webbrowser.open(url, new=2):
+        raise ProzorroError("Не вдалося відкрити посилання у браузері.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="prozorro-cli",
+        description="Отримання публічних даних про тендери Prozorro.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    tender_parser = subparsers.add_parser(
+        "tender",
+        help="отримати посилання, GUID або повний JSON тендера",
+    )
+    tender_parser.add_argument(
+        "reference",
+        metavar="REFERENCE",
+        help="UA-ID, GUID, UUID або посилання на тендер Prozorro",
+    )
+
+    output_group = tender_parser.add_mutually_exclusive_group()
+    output_group.add_argument(
+        "--link",
+        action="store_true",
+        help="вивести посилання на повний JSON у Public API",
+    )
+    output_group.add_argument(
+        "--link-html",
+        "--linkhtml",
+        dest="link_html",
+        action="store_true",
+        help="вивести посилання на HTML-сторінку тендера",
+    )
+    output_group.add_argument(
+        "--guid",
+        action="store_true",
+        help="вивести внутрішній id Prozorro без дефісів",
+    )
+    output_group.add_argument(
+        "--guid-normal",
+        action="store_true",
+        help="вивести внутрішній id у стандартному форматі UUID",
+    )
+    tender_parser.add_argument(
+        "--open",
+        action="store_true",
+        help="відкрити посилання з --link або --link-html у браузері",
+    )
+
+    documents_parser = subparsers.add_parser(
+        "documents",
+        help="завантажити всі файли з data.documents тендера",
+    )
+    documents_parser.add_argument(
+        "reference",
+        metavar="REFERENCE",
+        help="UA-ID, GUID, UUID або посилання на тендер Prozorro",
+    )
+    documents_parser.add_argument(
+        "--output",
+        required=True,
+        metavar="DIRECTORY",
+        help="каталог для завантажених документів",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    configure_windows_streams()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "tender":
+            if args.open and not (args.link or args.link_html):
+                parser.error("--open потребує --link або --link-html.")
+
+            if args.link:
+                print_link(
+                    public_api_link(args.reference),
+                    open_in_browser=args.open,
+                )
+                return 0
+
+            if args.link_html:
+                print_link(
+                    tender_link(args.reference),
+                    open_in_browser=args.open,
+                )
+                return 0
+
+            if args.guid or args.guid_normal:
+                guid = resolve_guid(args.reference)
+                print(normal_guid(guid) if args.guid_normal else guid)
+                return 0
+
+            payload = fetch_tender(args.reference)
+            json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+            sys.stdout.write("\n")
+            return 0
+
+        if args.command == "documents":
+            downloaded = download_documents(args.reference, args.output)
+            for path in downloaded:
+                print(path)
+            print(f"Завантажено документів: {len(downloaded)}")
+            return 0
+    except ProzorroError as error:
+        parser.exit(1, f"Помилка: {error}\n")
+
+    parser.error("Невідома команда.")
+    return 2

prozorro_cli-0.1.0/src/prozorro_cli/client.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, unquote, urlsplit
+from urllib.request import Request, urlopen
+
+
+SUMMARY_URL = "https://prozorro.gov.ua/api/tenders/{tender_id}/summary"
+PUBLIC_API_URL = "https://public-api.prozorro.gov.ua/api/2.5/tenders/{guid}"
+TENDER_PAGE_URL = "https://prozorro.gov.ua/tender/{tender_id}"
+
+TENDER_ID_PATTERN = re.compile(r"^UA-\d{4}-\d{2}-\d{2}-\d{6}-[a-z]$")
+GUID_PATTERN = re.compile(r"^[0-9a-fA-F]{32}$")
+NORMAL_GUID_PATTERN = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+    r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+SUPPORTED_HOSTS = {
+    "prozorro.gov.ua",
+    "www.prozorro.gov.ua",
+    "public-api.prozorro.gov.ua",
+}
+INVALID_FILENAME_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+WINDOWS_RESERVED_FILENAMES = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{number}" for number in range(1, 10)),
+    *(f"LPT{number}" for number in range(1, 10)),
+}
+
+
+class ProzorroError(RuntimeError):
+    """A user-facing error returned by Prozorro or the network."""
+
+
+@dataclass(frozen=True)
+class TenderReference:
+    tender_id: str | None = None
+    guid: str | None = None
+
+
+def validate_tender_id(tender_id: str) -> str:
+    if not TENDER_ID_PATTERN.fullmatch(tender_id):
+        raise ProzorroError(
+            "Некоректний номер тендера. Очікується формат "
+            "UA-YYYY-MM-DD-NNNNNN-x."
+        )
+    return tender_id
+
+
+def compact_guid(guid: str) -> str:
+    if GUID_PATTERN.fullmatch(guid):
+        return guid.lower()
+    if NORMAL_GUID_PATTERN.fullmatch(guid):
+        return guid.replace("-", "").lower()
+    raise ProzorroError("Некоректний внутрішній id Prozorro.")
+
+
+def parse_tender_reference(value: str) -> TenderReference:
+    candidate = value.strip()
+    if TENDER_ID_PATTERN.fullmatch(candidate):
+        return TenderReference(tender_id=candidate)
+    if GUID_PATTERN.fullmatch(candidate) or NORMAL_GUID_PATTERN.fullmatch(candidate):
+        return TenderReference(guid=compact_guid(candidate))
+
+    parsed = urlsplit(candidate)
+    if parsed.scheme not in {"http", "https"} or parsed.hostname not in SUPPORTED_HOSTS:
+        raise ProzorroError(
+            "Очікується UA-ID, GUID, UUID або посилання на тендер Prozorro."
+        )
+
+    parts = [unquote(part) for part in parsed.path.strip("/").split("/") if part]
+    if len(parts) == 2 and parts[0] == "tender":
+        return TenderReference(tender_id=validate_tender_id(parts[1]))
+    if len(parts) == 3 and parts[0] in {"uk", "en"} and parts[1] == "tender":
+        return TenderReference(tender_id=validate_tender_id(parts[2]))
+    if (
+        len(parts) == 4
+        and parts[0:2] == ["api", "tenders"]
+        and parts[3] == "summary"
+    ):
+        return TenderReference(tender_id=validate_tender_id(parts[2]))
+    if (
+        len(parts) == 4
+        and parts[0:3] == ["api", "2.5", "tenders"]
+    ):
+        return TenderReference(guid=compact_guid(parts[3]))
+
+    raise ProzorroError("Посилання не веде на підтримуваний тендер Prozorro.")
+
+
+def tender_link(reference: str, *, timeout: float = 30.0) -> str:
+    tender_id = resolve_tender_id(reference, timeout=timeout)
+    return TENDER_PAGE_URL.format(tender_id=quote(tender_id, safe=""))
+
+
+def public_api_link(reference: str, *, timeout: float = 30.0) -> str:
+    guid = resolve_guid(reference, timeout=timeout)
+    return PUBLIC_API_URL.format(guid=guid)
+
+
+def fetch_json(url: str, *, timeout: float = 30.0) -> dict[str, Any]:
+    request = Request(
+        url,
+        headers={
+            "Accept": "application/json",
+            "Accept-Language": "uk",
+            "User-Agent": "prozorro-cli/0.1 (+https://prozorro.gov.ua)",
+        },
+    )
+
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            payload = json.load(response)
+    except HTTPError as error:
+        if error.code == 404:
+            raise ProzorroError("Тендер не знайдено.") from error
+        raise ProzorroError(f"Prozorro повернув HTTP {error.code}.") from error
+    except URLError as error:
+        reason = getattr(error, "reason", error)
+        raise ProzorroError(f"Не вдалося підключитися до Prozorro: {reason}") from error
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        raise ProzorroError("Prozorro повернув некоректний JSON.") from error
+
+    if not isinstance(payload, dict):
+        raise ProzorroError("Prozorro повернув JSON неочікуваного формату.")
+    return payload
+
+
+def resolve_guid(reference: str, *, timeout: float = 30.0) -> str:
+    parsed = parse_tender_reference(reference)
+    if parsed.guid is not None:
+        return parsed.guid
+
+    tender_id = parsed.tender_id
+    if tender_id is None:
+        raise ProzorroError("Не вдалося визначити номер тендера.")
+    url = SUMMARY_URL.format(tender_id=quote(tender_id, safe=""))
+    summary = fetch_json(url, timeout=timeout)
+    guid = summary.get("id")
+
+    if not isinstance(guid, str) or not GUID_PATTERN.fullmatch(guid):
+        raise ProzorroError("У відповіді Prozorro немає коректного внутрішнього id.")
+    return guid.lower()
+
+
+def normal_guid(guid: str) -> str:
+    normalized = compact_guid(guid)
+    return (
+        f"{normalized[0:8]}-{normalized[8:12]}-{normalized[12:16]}-"
+        f"{normalized[16:20]}-{normalized[20:32]}"
+    )
+
+
+def fetch_tender(reference: str, *, timeout: float = 30.0) -> dict[str, Any]:
+    guid = resolve_guid(reference, timeout=timeout)
+    url = PUBLIC_API_URL.format(guid=guid)
+    return fetch_json(url, timeout=timeout)
+
+
+def safe_document_filename(value: str, *, fallback: str) -> str:
+    filename = INVALID_FILENAME_CHARS.sub("_", value).strip().rstrip(". ")
+    if not filename:
+        filename = fallback
+
+    stem = filename.split(".", 1)[0].upper()
+    if stem in WINDOWS_RESERVED_FILENAMES:
+        filename = f"_{filename}"
+    return filename
+
+
+def available_path(directory: Path, filename: str) -> Path:
+    candidate = directory / filename
+    if not candidate.exists():
+        return candidate
+
+    suffix = candidate.suffix
+    stem = candidate.name[: -len(suffix)] if suffix else candidate.name
+    number = 2
+    while True:
+        candidate = directory / f"{stem} ({number}){suffix}"
+        if not candidate.exists():
+            return candidate
+        number += 1
+
+
+def download_document(
+    url: str,
+    destination: Path,
+    *,
+    timeout: float = 30.0,
+) -> None:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ProzorroError("Документ містить некоректне посилання.")
+
+    request = Request(
+        url,
+        headers={"User-Agent": "prozorro-cli/0.1 (+https://prozorro.gov.ua)"},
+    )
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            with destination.open("xb") as output:
+                shutil.copyfileobj(response, output)
+    except HTTPError as error:
+        destination.unlink(missing_ok=True)
+        raise ProzorroError(
+            f"Не вдалося завантажити документ: HTTP {error.code}."
+        ) from error
+    except URLError as error:
+        destination.unlink(missing_ok=True)
+        reason = getattr(error, "reason", error)
+        raise ProzorroError(
+            f"Не вдалося завантажити документ: {reason}"
+        ) from error
+    except OSError as error:
+        destination.unlink(missing_ok=True)
+        raise ProzorroError(
+            f"Не вдалося зберегти документ «{destination.name}»: {error}"
+        ) from error
+
+
+def download_documents(
+    reference: str,
+    output: str | Path,
+    *,
+    timeout: float = 30.0,
+) -> list[Path]:
+    payload = fetch_tender(reference, timeout=timeout)
+    data = payload.get("data")
+    documents = data.get("documents") if isinstance(data, dict) else None
+    if not isinstance(documents, list):
+        raise ProzorroError("У відповіді Prozorro немає масиву data.documents.")
+
+    output_directory = Path(output).expanduser()
+    try:
+        output_directory.mkdir(parents=True, exist_ok=True)
+    except OSError as error:
+        raise ProzorroError(
+            f"Не вдалося створити каталог «{output_directory}»: {error}"
+        ) from error
+    if not output_directory.is_dir():
+        raise ProzorroError(f"Шлях «{output_directory}» не є каталогом.")
+
+    downloaded: list[Path] = []
+    for index, document in enumerate(documents, start=1):
+        if not isinstance(document, dict):
+            raise ProzorroError(
+                f"Документ #{index} у data.documents має некоректний формат."
+            )
+
+        url = document.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise ProzorroError(
+                f"Документ #{index} у data.documents не містить url."
+            )
+
+        document_id = document.get("id")
+        fallback = (
+            document_id
+            if isinstance(document_id, str) and document_id.strip()
+            else f"document-{index}"
+        )
+        title = document.get("title")
+        filename = safe_document_filename(
+            title if isinstance(title, str) else "",
+            fallback=fallback,
+        )
+        destination = available_path(output_directory, filename)
+        download_document(url, destination, timeout=timeout)
+        downloaded.append(destination)
+
+    return downloaded
+
+
+def resolve_tender_id(reference: str, *, timeout: float = 30.0) -> str:
+    parsed = parse_tender_reference(reference)
+    if parsed.tender_id is not None:
+        return parsed.tender_id
+
+    guid = parsed.guid
+    if guid is None:
+        raise ProzorroError("Не вдалося визначити внутрішній id Prozorro.")
+    payload = fetch_json(PUBLIC_API_URL.format(guid=guid), timeout=timeout)
+    data = payload.get("data")
+    tender_id = data.get("tenderID") if isinstance(data, dict) else None
+    if not isinstance(tender_id, str):
+        raise ProzorroError("У відповіді Prozorro немає номера тендера.")
+    return validate_tender_id(tender_id)

prozorro_cli-0.1.0/src/prozorro_cli.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: prozorro-cli
+Version: 0.1.0
+Summary: Small command-line client for public Prozorro tender data
+Author: prozorro-cli contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/radimbig2/prozorro-cli
+Project-URL: Issues, https://github.com/radimbig2/prozorro-cli/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# prozorro-cli
+
+Невелика CLI для отримання публічних даних про тендери Prozorro за UA-ID,
+внутрішнім GUID, стандартним UUID або посиланням.
+
+## Встановлення
+
+```powershell
+pip install prozorro-cli
+prozorro-cli --help
+```
+
+Для ізольованого глобального встановлення CLI також можна використати
+`pipx install prozorro-cli`.
+
+## Команди
+
+```powershell
+# Посилання на повний JSON у Public API
+prozorro-cli tender UA-2026-06-15-003439-a --link
+
+# Посилання на HTML-сторінку тендера
+prozorro-cli tender UA-2026-06-15-003439-a --link-html
+
+# Надрукувати й відкрити JSON Public API у браузері
+prozorro-cli tender UA-2026-06-15-003439-a --link --open
+
+# Надрукувати й відкрити HTML-сторінку у браузері
+prozorro-cli tender UA-2026-06-15-003439-a --link-html --open
+
+# Скорочений alias для --link-html
+prozorro-cli tender UA-2026-06-15-003439-a --linkhtml --open
+
+# Внутрішній id Prozorro
+prozorro-cli tender UA-2026-06-15-003439-a --guid
+
+# Той самий id у стандартному форматі UUID
+prozorro-cli tender UA-2026-06-15-003439-a --guid-normal
+
+# Повний JSON із public-api.prozorro.gov.ua
+prozorro-cli tender UA-2026-06-15-003439-a
+
+# Повний JSON за GUID без дефісів
+prozorro-cli tender 5d2590ef8a1b455f8d09ceeae474b21f
+
+# Повний JSON за стандартним UUID
+prozorro-cli tender 5d2590ef-8a1b-455f-8d09-ceeae474b21f
+
+# Повний JSON за посиланням на сторінку тендера
+prozorro-cli tender https://prozorro.gov.ua/tender/UA-2026-06-15-003439-a
+
+# Повний JSON за посиланням Public API
+prozorro-cli tender https://public-api.prozorro.gov.ua/api/2.5/tenders/5d2590ef8a1b455f8d09ceeae474b21f
+
+# Завантажити всі файли з data.documents за посиланням Public API
+prozorro-cli documents https://public-api.prozorro.gov.ua/api/2.5/tenders/5d2590ef8a1b455f8d09ceeae474b21f --output /temp
+
+# Те саме за UA-ID
+prozorro-cli documents UA-2026-06-15-003439-a --output /temp
+```
+
+Для UA-ID і посилання на сторінку CLI спочатку отримує внутрішній `id` через
+публічний endpoint `https://prozorro.gov.ua/api/tenders/<UA-ID>/summary`.
+Для GUID, UUID і посилання Public API цей крок пропускається. Повний JSON
+завантажується з `https://public-api.prozorro.gov.ua/api/2.5/tenders/<id>`.
+
+Команда `documents` створює каталог із `--output`, якщо його ще немає, і
+завантажує туди всі файли з `data.documents`. Імена беруться з `title`;
+однакові імена не перезаписуються, а отримують суфікси `(2)`, `(3)` тощо.
+
+## Розробка
+
+```powershell
+$env:PYTHONPATH = "$PWD\src"
+python -m unittest discover -s tests -v
+python -m prozorro_cli tender UA-2026-06-15-003439-a --guid
+```
+
+## Реліз
+
+1. Оновіть `version` у `pyproject.toml` та `__version__` у
+   `src/prozorro_cli/__init__.py`.
+2. Створіть і опублікуйте GitHub Release з тегом тієї ж версії, наприклад
+   `v0.1.0`.
+3. GitHub Actions перевірить тести, збере wheel і sdist, додасть їх до Release
+   та опублікує пакет у PyPI.
+
+Для публікації потрібен GitHub Actions secret `PYPI_API_TOKEN` з API-токеном
+PyPI. Job публікації запускається в GitHub environment `pypi`.

prozorro_cli-0.1.0/src/prozorro_cli.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/prozorro_cli/__init__.py
+src/prozorro_cli/__main__.py
+src/prozorro_cli/cli.py
+src/prozorro_cli/client.py
+src/prozorro_cli.egg-info/PKG-INFO
+src/prozorro_cli.egg-info/SOURCES.txt
+src/prozorro_cli.egg-info/dependency_links.txt
+src/prozorro_cli.egg-info/entry_points.txt
+src/prozorro_cli.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_client.py

prozorro_cli-0.1.0/src/prozorro_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

prozorro_cli-0.1.0/src/prozorro_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prozorro-cli = prozorro_cli.cli:main

prozorro_cli-0.1.0/src/prozorro_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+prozorro_cli

prozorro_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import io
+import json
+import unittest
+from contextlib import redirect_stdout
+from unittest.mock import patch
+
+from prozorro_cli.cli import main
+
+
+TENDER_ID = "UA-2026-06-15-003439-a"
+GUID = "5d2590ef8a1b455f8d09ceeae474b21f"
+NORMAL_GUID = "5d2590ef-8a1b-455f-8d09-ceeae474b21f"
+
+
+class CliTests(unittest.TestCase):
+    def run_cli(self, *arguments: str) -> tuple[int, str]:
+        stdout = io.StringIO()
+        with redirect_stdout(stdout):
+            exit_code = main(list(arguments))
+        return exit_code, stdout.getvalue()
+
+    @patch(
+        "prozorro_cli.cli.public_api_link",
+        return_value=(
+            "https://public-api.prozorro.gov.ua/api/2.5/tenders/"
+            f"{GUID}"
+        ),
+    )
+    def test_link(self, public_api_link_mock) -> None:
+        exit_code, output = self.run_cli("tender", TENDER_ID, "--link")
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(
+            output,
+            "https://public-api.prozorro.gov.ua/api/2.5/tenders/"
+            f"{GUID}\n",
+        )
+        public_api_link_mock.assert_called_once_with(TENDER_ID)
+
+    def test_link_html(self) -> None:
+        exit_code, output = self.run_cli("tender", TENDER_ID, "--link-html")
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(
+            output,
+            f"https://prozorro.gov.ua/tender/{TENDER_ID}\n",
+        )
+
+    def test_linkhtml_alias(self) -> None:
+        exit_code, output = self.run_cli("tender", TENDER_ID, "--linkhtml")
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(
+            output,
+            f"https://prozorro.gov.ua/tender/{TENDER_ID}\n",
+        )
+
+    @patch("prozorro_cli.cli.webbrowser.open", return_value=True)
+    @patch(
+        "prozorro_cli.cli.public_api_link",
+        return_value=(
+            "https://public-api.prozorro.gov.ua/api/2.5/tenders/"
+            f"{GUID}"
+        ),
+    )
+    def test_link_open(
+        self,
+        public_api_link_mock,
+        browser_open_mock,
+    ) -> None:
+        exit_code, output = self.run_cli(
+            "tender",
+            TENDER_ID,
+            "--link",
+            "--open",
+        )
+
+        api_url = (
+            "https://public-api.prozorro.gov.ua/api/2.5/tenders/"
+            f"{GUID}"
+        )
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(output, f"{api_url}\n")
+        public_api_link_mock.assert_called_once_with(TENDER_ID)
+        browser_open_mock.assert_called_once_with(api_url, new=2)
+
+    @patch("prozorro_cli.cli.webbrowser.open", return_value=True)
+    def test_link_html_open(self, browser_open_mock) -> None:
+        exit_code, output = self.run_cli(
+            "tender",
+            TENDER_ID,
+            "--linkhtml",
+            "--open",
+        )
+
+        html_url = f"https://prozorro.gov.ua/tender/{TENDER_ID}"
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(output, f"{html_url}\n")
+        browser_open_mock.assert_called_once_with(html_url, new=2)
+
+    def test_stream_configuration_is_safe_with_string_io(self) -> None:
+        exit_code, output = self.run_cli("tender", TENDER_ID, "--link-html")
+
+        self.assertEqual(exit_code, 0)
+        self.assertIn(TENDER_ID, output)
+
+    @patch("prozorro_cli.cli.resolve_guid", return_value=GUID)
+    def test_guid(self, resolve_guid_mock) -> None:
+        exit_code, output = self.run_cli("tender", TENDER_ID, "--guid")
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(output, f"{GUID}\n")
+        resolve_guid_mock.assert_called_once_with(TENDER_ID)
+
+    @patch("prozorro_cli.cli.resolve_guid", return_value=GUID)
+    def test_guid_normal(self, resolve_guid_mock) -> None:
+        exit_code, output = self.run_cli("tender", TENDER_ID, "--guid-normal")
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(output, "5d2590ef-8a1b-455f-8d09-ceeae474b21f\n")
+        resolve_guid_mock.assert_called_once_with(TENDER_ID)
+
+    @patch("prozorro_cli.cli.fetch_tender")
+    def test_default_prints_full_json(self, fetch_tender_mock) -> None:
+        fetch_tender_mock.return_value = {
+            "data": {
+                "id": GUID,
+                "tenderID": TENDER_ID,
+                "title": "Електрична енергія",
+            }
+        }
+
+        exit_code, output = self.run_cli("tender", TENDER_ID)
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(json.loads(output)["data"]["id"], GUID)
+        self.assertIn("Електрична енергія", output)
+
+    @patch("prozorro_cli.cli.fetch_tender")
+    def test_default_passes_normal_uuid_to_client(self, fetch_tender_mock) -> None:
+        fetch_tender_mock.return_value = {
+            "data": {"id": GUID, "tenderID": TENDER_ID}
+        }
+
+        exit_code, output = self.run_cli("tender", NORMAL_GUID)
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(json.loads(output)["data"]["id"], GUID)
+        fetch_tender_mock.assert_called_once_with(NORMAL_GUID)
+
+    @patch("prozorro_cli.cli.download_documents")
+    def test_documents_downloads_to_output(self, download_documents_mock) -> None:
+        download_documents_mock.return_value = [
+            "/temp/specification.pdf",
+            "/temp/contract.docx",
+        ]
+
+        exit_code, output = self.run_cli(
+            "documents",
+            TENDER_ID,
+            "--output",
+            "/temp",
+        )
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(
+            output,
+            "/temp/specification.pdf\n"
+            "/temp/contract.docx\n"
+            "Завантажено документів: 2\n",
+        )
+        download_documents_mock.assert_called_once_with(TENDER_ID, "/temp")
+
+
+if __name__ == "__main__":
+    unittest.main()

prozorro_cli-0.1.0/tests/test_client.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import unittest
+from io import BytesIO
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest.mock import patch
+
+from prozorro_cli.client import (
+    ProzorroError,
+    compact_guid,
+    download_document,
+    download_documents,
+    fetch_tender,
+    normal_guid,
+    parse_tender_reference,
+    public_api_link,
+    resolve_guid,
+    resolve_tender_id,
+    safe_document_filename,
+    tender_link,
+)
+
+
+TENDER_ID = "UA-2026-06-15-003439-a"
+GUID = "5d2590ef8a1b455f8d09ceeae474b21f"
+NORMAL_GUID = "5d2590ef-8a1b-455f-8d09-ceeae474b21f"
+
+
+class ClientTests(unittest.TestCase):
+    def test_tender_link(self) -> None:
+        self.assertEqual(
+            tender_link(TENDER_ID),
+            f"https://prozorro.gov.ua/tender/{TENDER_ID}",
+        )
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_public_api_link_from_tender_id(self, fetch_json_mock) -> None:
+        fetch_json_mock.return_value = {"id": GUID, "tenderID": TENDER_ID}
+
+        self.assertEqual(
+            public_api_link(TENDER_ID),
+            f"https://public-api.prozorro.gov.ua/api/2.5/tenders/{GUID}",
+        )
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_public_api_link_from_uuid_skips_network(self, fetch_json_mock) -> None:
+        self.assertEqual(
+            public_api_link(NORMAL_GUID),
+            f"https://public-api.prozorro.gov.ua/api/2.5/tenders/{GUID}",
+        )
+        fetch_json_mock.assert_not_called()
+
+    def test_invalid_reference_is_rejected(self) -> None:
+        with self.assertRaisesRegex(ProzorroError, "Очікується UA-ID"):
+            tender_link("not-a-tender")
+
+    def test_normal_guid(self) -> None:
+        self.assertEqual(normal_guid(GUID), NORMAL_GUID)
+
+    def test_compact_guid_accepts_normal_uuid(self) -> None:
+        self.assertEqual(compact_guid(NORMAL_GUID), GUID)
+
+    def test_parse_tender_page_links(self) -> None:
+        for url in (
+            f"https://prozorro.gov.ua/tender/{TENDER_ID}",
+            f"https://prozorro.gov.ua/uk/tender/{TENDER_ID}",
+            f"https://prozorro.gov.ua/en/tender/{TENDER_ID}?source=test",
+        ):
+            with self.subTest(url=url):
+                self.assertEqual(parse_tender_reference(url).tender_id, TENDER_ID)
+
+    def test_parse_summary_link(self) -> None:
+        reference = parse_tender_reference(
+            f"https://prozorro.gov.ua/api/tenders/{TENDER_ID}/summary"
+        )
+        self.assertEqual(reference.tender_id, TENDER_ID)
+
+    def test_parse_public_api_links(self) -> None:
+        for guid in (GUID, NORMAL_GUID):
+            url = f"https://public-api.prozorro.gov.ua/api/2.5/tenders/{guid}"
+            with self.subTest(url=url):
+                self.assertEqual(parse_tender_reference(url).guid, GUID)
+
+    def test_unsupported_link_is_rejected(self) -> None:
+        with self.assertRaisesRegex(ProzorroError, "підтримуваний тендер"):
+            parse_tender_reference("https://prozorro.gov.ua/plans/example")
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_resolve_guid_uses_summary_endpoint(self, fetch_json_mock) -> None:
+        fetch_json_mock.return_value = {"id": GUID, "tenderID": TENDER_ID}
+
+        self.assertEqual(resolve_guid(TENDER_ID), GUID)
+        fetch_json_mock.assert_called_once_with(
+            f"https://prozorro.gov.ua/api/tenders/{TENDER_ID}/summary",
+            timeout=30.0,
+        )
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_resolve_guid_from_uuid_does_not_call_network(
+        self, fetch_json_mock
+    ) -> None:
+        self.assertEqual(resolve_guid(NORMAL_GUID), GUID)
+        fetch_json_mock.assert_not_called()
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_resolve_guid_rejects_missing_id(self, fetch_json_mock) -> None:
+        fetch_json_mock.return_value = {"tenderID": TENDER_ID}
+
+        with self.assertRaisesRegex(ProzorroError, "внутрішнього id"):
+            resolve_guid(TENDER_ID)
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_fetch_tender_uses_resolved_guid(self, fetch_json_mock) -> None:
+        fetch_json_mock.side_effect = [
+            {"id": GUID, "tenderID": TENDER_ID},
+            {"data": {"id": GUID, "tenderID": TENDER_ID}},
+        ]
+
+        payload = fetch_tender(TENDER_ID)
+
+        self.assertEqual(payload["data"]["id"], GUID)
+        self.assertEqual(
+            fetch_json_mock.call_args_list[1].args[0],
+            f"https://public-api.prozorro.gov.ua/api/2.5/tenders/{GUID}",
+        )
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_fetch_tender_by_guid_skips_summary(self, fetch_json_mock) -> None:
+        fetch_json_mock.return_value = {
+            "data": {"id": GUID, "tenderID": TENDER_ID}
+        }
+
+        payload = fetch_tender(NORMAL_GUID)
+
+        self.assertEqual(payload["data"]["id"], GUID)
+        fetch_json_mock.assert_called_once_with(
+            f"https://public-api.prozorro.gov.ua/api/2.5/tenders/{GUID}",
+            timeout=30.0,
+        )
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_resolve_tender_id_from_guid(self, fetch_json_mock) -> None:
+        fetch_json_mock.return_value = {
+            "data": {"id": GUID, "tenderID": TENDER_ID}
+        }
+
+        self.assertEqual(resolve_tender_id(GUID), TENDER_ID)
+
+    @patch("prozorro_cli.client.fetch_json")
+    def test_tender_link_from_guid(self, fetch_json_mock) -> None:
+        fetch_json_mock.return_value = {
+            "data": {"id": GUID, "tenderID": TENDER_ID}
+        }
+
+        self.assertEqual(
+            tender_link(GUID),
+            f"https://prozorro.gov.ua/tender/{TENDER_ID}",
+        )
+
+    def test_safe_document_filename(self) -> None:
+        self.assertEqual(
+            safe_document_filename('contract: final?.pdf', fallback="document-1"),
+            "contract_ final_.pdf",
+        )
+        self.assertEqual(
+            safe_document_filename("CON", fallback="document-1"),
+            "_CON",
+        )
+
+    @patch("prozorro_cli.client.urlopen")
+    def test_download_document_writes_response_bytes(self, urlopen_mock) -> None:
+        response = BytesIO(b"document contents")
+        urlopen_mock.return_value.__enter__.return_value = response
+
+        with TemporaryDirectory() as temporary_directory:
+            destination = Path(temporary_directory) / "document.pdf"
+
+            download_document(
+                "https://public-docs.prozorro.gov.ua/document",
+                destination,
+            )
+
+            self.assertEqual(destination.read_bytes(), b"document contents")
+
+    @patch("prozorro_cli.client.download_document")
+    @patch("prozorro_cli.client.fetch_tender")
+    def test_download_documents_uses_data_documents(
+        self,
+        fetch_tender_mock,
+        download_document_mock,
+    ) -> None:
+        download_document_mock.side_effect = (
+            lambda _url, destination, **_kwargs: destination.touch()
+        )
+        fetch_tender_mock.return_value = {
+            "data": {
+                "documents": [
+                    {
+                        "id": "first-id",
+                        "title": "specification.pdf",
+                        "url": "https://public-docs.prozorro.gov.ua/specification",
+                    },
+                    {
+                        "id": "second-id",
+                        "title": "specification.pdf",
+                        "url": "https://public-docs.prozorro.gov.ua/contract",
+                    },
+                ]
+            }
+        }
+
+        with TemporaryDirectory() as temporary_directory:
+            first_existing = Path(temporary_directory) / "specification.pdf"
+            first_existing.write_bytes(b"existing")
+
+            result = download_documents(TENDER_ID, temporary_directory)
+
+        self.assertEqual(
+            [path.name for path in result],
+            ["specification (2).pdf", "specification (3).pdf"],
+        )
+        self.assertEqual(download_document_mock.call_count, 2)
+
+    @patch("prozorro_cli.client.fetch_tender")
+    def test_download_documents_requires_document_url(
+        self,
+        fetch_tender_mock,
+    ) -> None:
+        fetch_tender_mock.return_value = {
+            "data": {"documents": [{"title": "missing-url.pdf"}]}
+        }
+
+        with TemporaryDirectory() as temporary_directory:
+            with self.assertRaisesRegex(ProzorroError, "не містить url"):
+                download_documents(TENDER_ID, temporary_directory)
+
+
+if __name__ == "__main__":
+    unittest.main()