yandex-cli 0.1.0__py3-none-any.whl

ycli/yandex/forms/answers/__init__.py

@@ -0,0 +1 @@
+"""Forms /surveys/{id}/answers resource package."""

ycli/yandex/forms/answers/cli.py

@@ -0,0 +1,25 @@
+"""`forms answers` commands."""
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ycli.yandex.forms._clideps import forms_client
+
+app = typer.Typer(name="answers", help="Forms answers.", no_args_is_help=True)
+
+SurveyIdArg = Annotated[
+    str, typer.Argument(metavar="SURVEY_ID", help="Form id, e.g. 6818ceffe010db4f59d11329.")
+]
+
+
+@app.callback()
+def _group() -> None:
+    """Group anchor — forces subcommand dispatch (no eager DI, so --help stays cred-free)."""
+
+
+@app.command("list")
+def list_(ctx: typer.Context, survey_id: SurveyIdArg) -> None:
+    """List ALL of a form's responses (drains every page via the next cursor)."""
+    print(forms_client(ctx).answers.list_all(survey_id).model_dump_json(by_alias=True))

ycli/yandex/forms/answers/client.py

@@ -0,0 +1,57 @@
+"""Declarative Forms answers client (uplink) — transport ONLY.
+
+NOTE: no ``from __future__ import annotations`` — uplink reads annotations eagerly.
+"""
+from urllib.parse import urljoin
+
+import uplink
+
+from ycli.yandex.forms._base import FormsResource
+from ycli.yandex.forms.answers.models import AnswersResponse
+
+
+class AnswersClient(FormsResource):
+    """Declarative HTTP for ``/surveys/{id}/answers``."""
+
+    @uplink.timeout(30)
+    @uplink.returns.json()
+    @uplink.get("surveys/{survey_id}/answers")
+    def list(self, survey_id: uplink.Path) -> AnswersResponse:  # ty: ignore[empty-body]
+        """``GET /surveys/{id}/answers`` → the ``{columns, answers, next}`` envelope (verbatim).
+
+        Example:
+            >>> client = FormsClient.from_env()  # doctest: +SKIP
+            >>> client.answers.list(survey_id="686d0a1b2c3d4e5f").columns[0].slug  # doctest: +SKIP
+            'answer_short_text_1'
+        """
+
+    def list_all(self, survey_id: str) -> AnswersResponse:
+        """Drain *every* page of responses into one merged envelope.
+
+        The single-page :meth:`list` under-reports — the API paginates via the ``id``
+        cursor and hands the next page back as ``next.next_url`` (null when exhausted).
+        Follow that link verbatim (HATEOAS-style — no fragile cursor reconstruction)
+        until it is null, concatenating ``answers``. ``columns`` are taken from the
+        first page (identical across pages); the merged ``next`` is always ``None``.
+
+        Example:
+            >>> client = FormsClient.from_env()  # doctest: +SKIP
+            >>> len(client.answers.list_all(survey_id="686d0a1b2c3d4e5f").answers)  # doctest: +SKIP
+            317
+        """
+        page = self.list(survey_id)
+        columns = page.columns
+        answers = list(page.answers)
+        seen: set[str] = set()
+        nxt = page.next
+        while isinstance(nxt, dict) and nxt.get("next_url"):
+            url = urljoin(self.base_url.rstrip("/") + "/", str(nxt["next_url"]))
+            if url in seen:  # defensive: a server pointing at itself must not hang us
+                break
+            seen.add(url)
+            resp = self._session.get(url)
+            resp.raise_for_status()
+            page = AnswersResponse.model_validate(resp.json())
+            answers.extend(page.answers)
+            nxt = page.next
+        return AnswersResponse(columns=columns, answers=answers, next=None)

ycli/yandex/forms/answers/mcp.py

@@ -0,0 +1,15 @@
+"""Forms answers FastMCP tool (reads-only)."""
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+from ycli.yandex.forms._deps import RO, TAGS, forms_client
+from ycli.yandex.forms.answers.models import AnswersResponse
+from ycli.yandex.forms.client import FormsClient
+
+mcp = FastMCP("forms-answers")
+
+
+@mcp.tool(name="answers_list", annotations=RO, tags=TAGS)
+def list_(survey_id: str, client: FormsClient = Depends(forms_client)) -> AnswersResponse:
+    """ALL of a form's responses (drains every page via the next cursor)."""
+    return client.answers.list_all(survey_id)

ycli/yandex/forms/answers/models.py

@@ -0,0 +1,54 @@
+"""Pydantic models for Forms answers (Column + Answer + AnswersResponse envelope)."""
+from __future__ import annotations
+
+from typing import Any
+
+from ycli.yandex.forms._models import _Lenient
+
+
+class Column(_Lenient):
+    """An answers-table column descriptor (``…/answers`` → ``columns[]``).
+
+    Example:
+        >>> Column.model_validate({"id": 1, "slug": "s", "type": "string", "text": "T"}).text
+        'T'
+    """
+
+    id: int | None = None
+    slug: str | None = None
+    type: str | None = None
+    text: str | None = None
+    has_scores: bool | None = None
+
+
+class Answer(_Lenient):
+    """A single form response (``…/answers`` → ``answers[]``).
+
+    ``data`` is **positional**, aligned to ``columns``; each element is a
+    ``{"value": …}`` dict or ``null``. Passed through verbatim as ``Any``
+    (``value`` is a ``str`` or ``list[str]``).
+
+    Example:
+        >>> Answer.model_validate({"id": 9, "created": "2026-01-01", "data": [{"value": "x"}]}).data
+        [{'value': 'x'}]
+    """
+
+    id: int | None = None
+    created: str | None = None
+    data: list[Any] = []
+
+
+class AnswersResponse(_Lenient):
+    """Envelope for ``GET …/answers`` — ``{columns, answers, next}``.
+
+    ``next`` is ``{"next_url": …}`` or ``null`` (a pagination cursor), passed
+    through as ``Any``.
+
+    Example:
+        >>> AnswersResponse.model_validate({"columns": [], "answers": [], "next": None}).answers
+        []
+    """
+
+    columns: list[Column] = []
+    answers: list[Answer] = []
+    next: Any = None

ycli/yandex/forms/cli.py

@@ -0,0 +1,16 @@
+"""Yandex Forms CLI — mounts the per-resource sub-apps (lazy client DI via _clideps)."""
+from __future__ import annotations
+
+import typer
+
+from ycli.yandex.forms.answers.cli import app as answers_app
+from ycli.yandex.forms.me.cli import app as me_app
+from ycli.yandex.forms.questions.cli import app as questions_app
+from ycli.yandex.forms.surveys.cli import app as surveys_app
+
+app = typer.Typer(name="forms", help="Yandex Forms read.", no_args_is_help=True)
+
+app.add_typer(me_app)
+app.add_typer(surveys_app)
+app.add_typer(questions_app)
+app.add_typer(answers_app)

ycli/yandex/forms/client.py

@@ -0,0 +1,29 @@
+"""FormsClient — composition root over the forms resource clients (one shared session)."""
+from __future__ import annotations
+
+import requests
+
+from ycli.yandex.base import session_from_env
+from ycli.yandex.forms.answers.client import AnswersClient
+from ycli.yandex.forms.me.client import MeClient
+from ycli.yandex.forms.questions.client import QuestionsClient
+from ycli.yandex.forms.surveys.client import SurveysClient
+
+
+class FormsClient:
+    """Holds the per-resource forms clients, all sharing one ``requests.Session``.
+
+    Example:
+        >>> FormsClient.from_env().me.get()  # doctest: +SKIP
+    """
+
+    def __init__(self, *, session: requests.Session) -> None:
+        self.me = MeClient(session=session)
+        self.surveys = SurveysClient(session=session)
+        self.questions = QuestionsClient(session=session)
+        self.answers = AnswersClient(session=session)
+
+    @classmethod
+    def from_env(cls) -> FormsClient:
+        """Build all sub-clients from one env-resolved session."""
+        return cls(session=session_from_env())

ycli/yandex/forms/mcp.py

@@ -0,0 +1,13 @@
+"""Forms FastMCP subserver — mounts the per-resource tool servers (reads-only)."""
+from fastmcp import FastMCP
+
+from ycli.yandex.forms.answers.mcp import mcp as answers_mcp
+from ycli.yandex.forms.me.mcp import mcp as me_mcp
+from ycli.yandex.forms.questions.mcp import mcp as questions_mcp
+from ycli.yandex.forms.surveys.mcp import mcp as surveys_mcp
+
+mcp = FastMCP("forms")
+mcp.mount(me_mcp)
+mcp.mount(surveys_mcp)
+mcp.mount(questions_mcp)
+mcp.mount(answers_mcp)

ycli/yandex/forms/me/__init__.py

@@ -0,0 +1 @@
+"""Forms /users/me resource package."""

ycli/yandex/forms/me/cli.py

@@ -0,0 +1,19 @@
+"""`forms me` commands."""
+from __future__ import annotations
+
+import typer
+
+from ycli.yandex.forms._clideps import forms_client
+
+app = typer.Typer(name="me", help="Forms authenticated user.", no_args_is_help=True)
+
+
+@app.callback()
+def _group() -> None:
+    """Group anchor — forces subcommand dispatch (no eager DI, so --help stays cred-free)."""
+
+
+@app.command()
+def get(ctx: typer.Context) -> None:
+    """Print the authenticated user (a safe auth probe)."""
+    print(forms_client(ctx).me.get().model_dump_json(by_alias=True))

ycli/yandex/forms/me/client.py

@@ -0,0 +1,25 @@
+"""Declarative Forms /users/me client (uplink) — transport ONLY.
+
+NOTE: do NOT add ``from __future__ import annotations`` — uplink reads parameter
+annotations eagerly.
+"""
+import uplink
+
+from ycli.yandex.forms._base import FormsResource
+from ycli.yandex.forms.me.models import User
+
+
+class MeClient(FormsResource):
+    """Declarative HTTP for ``/users/me``."""
+
+    @uplink.timeout(30)
+    @uplink.returns.json()
+    @uplink.get("users/me")
+    def get(self) -> User:  # ty: ignore[empty-body]
+        """``GET /users/me`` → the authenticated ``User`` (a safe auth probe).
+
+        Example:
+            >>> client = FormsClient.from_env()  # doctest: +SKIP
+            >>> client.me.get().email  # doctest: +SKIP
+            'znatnov.s@example.com'
+        """

ycli/yandex/forms/me/mcp.py

@@ -0,0 +1,20 @@
+"""Forms /users/me FastMCP tool (reads-only) — Depends DI, native error handling."""
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+from ycli.yandex.forms._deps import RO, TAGS, forms_client
+from ycli.yandex.forms.client import FormsClient
+from ycli.yandex.forms.me.models import User
+
+mcp = FastMCP("forms-me")
+
+
+@mcp.tool(name="me_get", annotations=RO, tags=TAGS)
+def get(client: FormsClient = Depends(forms_client)) -> User:
+    """The authenticated Yandex Forms user (a safe auth probe)."""
+    result = client.me.get()
+    # Forms models are fully lenient, so a 401/4xx deserializes into an all-None User
+    # instead of raising. Guard so the auth probe actually fails on failure.
+    if result.id is None:
+        raise ValueError("auth probe failed — empty user (check YANDEX_ID_OAUTH_TOKEN)")
+    return result

ycli/yandex/forms/me/models.py

@@ -0,0 +1,18 @@
+"""Pydantic model for Forms /users/me (User)."""
+from __future__ import annotations
+
+from ycli.yandex.forms._models import _Lenient
+
+
+class User(_Lenient):
+    """The authenticated user (``GET /v1/users/me``) — a safe auth probe.
+
+    Example:
+        >>> User.model_validate({"id": 1, "uid": "u", "cloud_uid": "c", "email": "e@x"}).email
+        'e@x'
+    """
+
+    id: int | None = None
+    uid: str | None = None
+    cloud_uid: str | None = None
+    email: str | None = None

ycli/yandex/forms/questions/__init__.py

@@ -0,0 +1 @@
+"""Forms /surveys/{id}/questions resource package."""

ycli/yandex/forms/questions/cli.py

@@ -0,0 +1,25 @@
+"""`forms questions` commands."""
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ycli.yandex.forms._clideps import forms_client
+
+app = typer.Typer(name="questions", help="Forms questions.", no_args_is_help=True)
+
+SurveyIdArg = Annotated[
+    str, typer.Argument(metavar="SURVEY_ID", help="Form id, e.g. 6818ceffe010db4f59d11329.")
+]
+
+
+@app.callback()
+def _group() -> None:
+    """Group anchor — forces subcommand dispatch (no eager DI, so --help stays cred-free)."""
+
+
+@app.command("list")
+def list_(ctx: typer.Context, survey_id: SurveyIdArg) -> None:
+    """List a form's questions (the {pages} envelope)."""
+    print(forms_client(ctx).questions.list(survey_id).model_dump_json(by_alias=True))

ycli/yandex/forms/questions/client.py

@@ -0,0 +1,24 @@
+"""Declarative Forms questions client (uplink) — transport ONLY.
+
+NOTE: no ``from __future__ import annotations`` — uplink reads annotations eagerly.
+"""
+import uplink
+
+from ycli.yandex.forms._base import FormsResource
+from ycli.yandex.forms.questions.models import QuestionsResponse
+
+
+class QuestionsClient(FormsResource):
+    """Declarative HTTP for ``/surveys/{id}/questions``."""
+
+    @uplink.timeout(30)
+    @uplink.returns.json()
+    @uplink.get("surveys/{survey_id}/questions")
+    def list(self, survey_id: uplink.Path) -> QuestionsResponse:  # ty: ignore[empty-body]
+        """``GET /surveys/{id}/questions`` → the ``{pages}`` envelope (verbatim).
+
+        Example:
+            >>> client = FormsClient.from_env()  # doctest: +SKIP
+            >>> client.questions.list(survey_id="686d0a1b2c3d4e5f").pages[0].items[0].slug  # doctest: +SKIP
+            'answer_short_text_1'
+        """

ycli/yandex/forms/questions/mcp.py

@@ -0,0 +1,15 @@
+"""Forms questions FastMCP tool (reads-only)."""
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+from ycli.yandex.forms._deps import RO, TAGS, forms_client
+from ycli.yandex.forms.client import FormsClient
+from ycli.yandex.forms.questions.models import QuestionsResponse
+
+mcp = FastMCP("forms-questions")
+
+
+@mcp.tool(name="questions_list", annotations=RO, tags=TAGS)
+def list_(survey_id: str, client: FormsClient = Depends(forms_client)) -> QuestionsResponse:
+    """A form's questions, grouped into pages (the {pages} envelope)."""
+    return client.questions.list(survey_id)

ycli/yandex/forms/questions/models.py

@@ -0,0 +1,46 @@
+"""Pydantic models for Forms questions (Question + Page + QuestionsResponse envelope)."""
+from __future__ import annotations
+
+from ycli.yandex.forms._models import _Lenient
+
+
+class Question(_Lenient):
+    """A single question item within a page (``…/questions`` → ``pages[].items[]``).
+
+    ``id`` is an **int**. Type-specific fields (``data_source``, ``items``,
+    ``validators``, ``conditions``, …) are lenient-ignored.
+
+    Example:
+        >>> Question.model_validate({"id": 1, "slug": "s", "type": "string", "label": "L"}).slug
+        's'
+    """
+
+    id: int | None = None
+    label: str | None = None
+    slug: str | None = None
+    type: str | None = None
+    hidden: bool | None = None
+    comment: str | None = None
+
+
+class Page(_Lenient):
+    """A page grouping questions (``…/questions`` → ``pages[]``).
+
+    Example:
+        >>> Page.model_validate({"id": 7, "items": [{"id": 1}]}).items[0].id
+        1
+    """
+
+    id: int | None = None
+    items: list[Question] = []
+
+
+class QuestionsResponse(_Lenient):
+    """Envelope for ``GET …/questions`` — ``{pages:[Page]}``.
+
+    Example:
+        >>> QuestionsResponse.model_validate({"pages": [{"items": [{"id": 1}]}]}).pages[0].items[0].id
+        1
+    """
+
+    pages: list[Page] = []

ycli/yandex/forms/surveys/__init__.py

@@ -0,0 +1 @@
+"""Forms /surveys resource package."""

ycli/yandex/forms/surveys/cli.py

@@ -0,0 +1,26 @@
+"""`forms surveys` commands."""
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ycli.yandex.forms._clideps import forms_client
+
+app = typer.Typer(name="surveys", help="Forms surveys.", no_args_is_help=True)
+
+SurveyIdArg = Annotated[
+    str, typer.Argument(metavar="SURVEY_ID", help="Form id, e.g. 6818ceffe010db4f59d11329.")
+]
+
+
+@app.command("list")
+def list_(ctx: typer.Context) -> None:
+    """List all forms (the {links, result} envelope)."""
+    print(forms_client(ctx).surveys.list().model_dump_json(by_alias=True))
+
+
+@app.command()
+def get(ctx: typer.Context, survey_id: SurveyIdArg) -> None:
+    """Print one form's settings for SURVEY_ID."""
+    print(forms_client(ctx).surveys.get(survey_id).model_dump_json(by_alias=True))

ycli/yandex/forms/surveys/client.py

@@ -0,0 +1,36 @@
+"""Declarative Forms /surveys client (uplink) — transport ONLY.
+
+NOTE: no ``from __future__ import annotations`` — uplink reads annotations eagerly.
+"""
+import uplink
+
+from ycli.yandex.forms._base import FormsResource
+from ycli.yandex.forms.surveys.models import Survey, SurveyList
+
+
+class SurveysClient(FormsResource):
+    """Declarative HTTP for ``/surveys`` (list envelope + single get)."""
+
+    @uplink.timeout(30)
+    @uplink.returns.json()
+    @uplink.get("surveys")
+    def list(self) -> SurveyList:  # ty: ignore[empty-body]
+        """``GET /surveys`` → the ``{links, result}`` envelope (verbatim).
+
+        Example:
+            >>> client = FormsClient.from_env()  # doctest: +SKIP
+            >>> client.surveys.list().result[0].name  # doctest: +SKIP
+            'Новая задача'
+        """
+
+    @uplink.timeout(30)
+    @uplink.returns.json()
+    @uplink.get("surveys/{survey_id}")
+    def get(self, survey_id: uplink.Path) -> Survey:  # ty: ignore[empty-body]
+        """``GET /surveys/{id}`` → a single ``Survey`` (settings).
+
+        Example:
+            >>> client = FormsClient.from_env()  # doctest: +SKIP
+            >>> client.surveys.get(survey_id="686d0a1b2c3d4e5f").is_published  # doctest: +SKIP
+            True
+        """

ycli/yandex/forms/surveys/mcp.py

@@ -0,0 +1,26 @@
+"""Forms /surveys FastMCP tools (reads-only)."""
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+from ycli.yandex.forms._deps import RO, TAGS, forms_client
+from ycli.yandex.forms.client import FormsClient
+from ycli.yandex.forms.surveys.models import Survey, SurveyList
+
+mcp = FastMCP("forms-surveys")
+
+
+@mcp.tool(name="surveys_list", annotations=RO, tags=TAGS)
+def list_(client: FormsClient = Depends(forms_client)) -> SurveyList:
+    """Every form (survey) the caller can see (the {links, result} envelope)."""
+    return client.surveys.list()
+
+
+@mcp.tool(name="surveys_get", annotations=RO, tags=TAGS)
+def get(survey_id: str, client: FormsClient = Depends(forms_client)) -> Survey:
+    """One form's settings by id."""
+    result = client.surveys.get(survey_id)
+    # A 404 deserializes into an all-None Survey (lenient model) rather than raising;
+    # turn that into a clean not-found error instead of a phantom empty object.
+    if result.id is None:
+        raise ValueError(f"survey {survey_id!r} not found (got empty response — check id or permissions)")
+    return result

ycli/yandex/forms/surveys/models.py

@@ -0,0 +1,44 @@
+"""Pydantic models for Forms /surveys (Survey + SurveyList envelope)."""
+from __future__ import annotations
+
+from typing import Any
+
+from ycli.yandex.forms._models import _Lenient
+
+
+class Survey(_Lenient):
+    """A form/survey (``GET /v1/surveys`` item and ``GET /v1/surveys/{id}``).
+
+    ``id`` is a hex ObjectId **string** (not numeric); ``answers`` is an int
+    response count. Settings-only fields (``texts``, ``followers``, …) are
+    lenient-ignored.
+
+    Example:
+        >>> Survey.model_validate({"id": "686d", "name": "F", "answers": 444}).answers
+        444
+    """
+
+    id: str | None = None
+    name: str | None = None
+    dir_id: str | None = None
+    collab_id: str | None = None
+    created: str | None = None
+    modified: str | None = None
+    language: str | None = None
+    is_published: bool | None = None
+    is_public: bool | None = None
+    is_banned: bool | None = None
+    answers: int | None = None
+    is_favourite: bool | None = None
+
+
+class SurveyList(_Lenient):
+    """Envelope for ``GET /v1/surveys`` — ``{links, result:[Survey]}``.
+
+    Example:
+        >>> SurveyList.model_validate({"result": [{"id": "a"}]}).result[0].id
+        'a'
+    """
+
+    links: dict[str, Any] = {}
+    result: list[Survey] = []

ycli/yandex/tracker/__init__.py

@@ -0,0 +1 @@
+"""Yandex Tracker SDK — pure per-resource clients (issues, comments, links, …)."""

ycli/yandex/tracker/_base.py

@@ -0,0 +1,14 @@
+"""Per-domain base — carries the Tracker API base_url; resource clients inherit it.
+
+NOTE: no ``from __future__ import annotations`` — resource clients subclass this and
+uplink reads their method annotations eagerly. Keep this module annotation-eager too.
+"""
+from typing import ClassVar
+
+from ycli.yandex.base import BaseYandex
+
+
+class TrackerResource(BaseYandex):
+    """Base for every Tracker resource client (inherits session DI + from_env)."""
+
+    base_url: ClassVar[str] = "https://api.tracker.yandex.net/v3"

ycli/yandex/tracker/_clideps.py

@@ -0,0 +1,46 @@
+"""Lazy Typer DI for the tracker CLI + the ``--field key=value`` JSON-coerce helper."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from ycli.yandex.tracker.client import TrackerClient
+
+
+def tracker_client(ctx: typer.Context) -> TrackerClient:
+    """Return the request-scoped TrackerClient, building it from env on first access.
+
+    Lazy so ``--help`` (which never runs a command body) needs no creds; cached on
+    ``ctx.obj`` so multiple accesses within one invocation share the session.
+
+    Example:
+        >>> tracker_client(ctx)  # doctest: +SKIP
+    """
+    if ctx.obj is None:
+        ctx.obj = TrackerClient.from_env()
+    return ctx.obj
+
+
+def parse_fields(items: list[str] | None) -> dict[str, Any]:
+    """Parse repeated ``--field key=value`` strings into a dict (gh ``-F`` model).
+
+    Each value is JSON-coerced (``123`` → int, ``true`` → bool, ``{"id":5}`` → object),
+    falling back to the raw string when it is not valid JSON. Raises ``typer.BadParameter``
+    when an item has no ``=``.
+
+    Example:
+        >>> parse_fields(["sprint=123", "name=hi"])
+        {'sprint': 123, 'name': 'hi'}
+    """
+    out: dict[str, Any] = {}
+    for item in items or []:
+        key, sep, raw = item.partition("=")
+        if not sep:
+            raise typer.BadParameter(f"--field must be key=value, got {item!r}")
+        try:
+            out[key] = json.loads(raw)
+        except json.JSONDecodeError:
+            out[key] = raw
+    return out

ycli/yandex/tracker/_deps.py

@@ -0,0 +1,10 @@
+"""FastMCP dependency provider for the tracker subserver — builds a TrackerClient per call."""
+from ycli.yandex.tracker.client import TrackerClient
+
+RO: dict[str, bool] = {"readOnlyHint": True}
+TAGS: set[str] = {"tracker"}
+
+
+def tracker_client() -> TrackerClient:
+    """Provide an env-built TrackerClient to tracker MCP tools (FastMCP caches within a call)."""
+    return TrackerClient.from_env()