feat: add custom type support

#31

examples/custom_fileds.py

@@ -0,0 +1,42 @@
+import asyncio
+
+from yatracker import YaTracker
+from yatracker.types import FullIssue
+
+# CAUTION! Don't store credentials in your code!
+ORG_ID = ...
+TOKEN = ...
+
+
+# Create your own custom Issue type:
+class HelpIssue(FullIssue, kw_only=True):
+    """Your own FullIssue type.
+
+    For example, you have some fields passed by external system.
+    One of them called 'userUsername', second - 'userId'.
+    """
+
+    user_username: str | None
+    user_id: int
+
+
+async def main() -> None:
+    """Run example."""
+    # define tracker (once)
+    tracker = YaTracker(ORG_ID, TOKEN)
+
+    # create an issue
+    issue = await tracker.create_issue(
+        summary="New Issue",
+        queue="KEY",
+        user_id=1234567890,
+        _type=HelpIssue,
+    )
+    print(issue.user_id)
+
+    # don't forget to close tracker on app shutdown (once)
+    await tracker.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

yatracker/tracker/base.py

@@ -81,7 +81,9 @@ def _prepare_payload(
         return {
             camel_case(k): _convert_value(v)
             for k, v in payload.items()
-            if k not in {"self", "cls", *exclude} and v is not None
+            if k not in {"self", "cls", *exclude}
+            and not k.startswith("_")
+            and v is not None
         }
 
     async def close(self) -> None:

yatracker/tracker/categories/issues.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, TypeVar
 
 from yatracker.tracker.base import BaseTracker
 from yatracker.types import (
@@ -12,9 +12,16 @@
     Transitions,
 )
 
+IssueT_co = TypeVar("IssueT_co", bound=FullIssue, covariant=True)
+
 
 class Issues(BaseTracker):
-    async def get_issue(self, issue_id: str, expand: str | None = None) -> FullIssue:
+    async def get_issue(
+        self,
+        issue_id: str,
+        expand: str | None = None,
+        _type: type[IssueT_co | FullIssue] = FullIssue,
+    ) -> IssueT_co | FullIssue:
         """Get issue parameters.
 
         Use this request to get information about an issue.
@@ -23,22 +30,23 @@ async def get_issue(self, issue_id: str, expand: str | None = None) -> FullIssue
         :param expand: Additional fields to include in the response:
                         transitions — Workflow transitions between statuses.
                         attachments — Attachments
-
+        :param _type: you can use your own extended FullIssue type
         :return:
         """
         data = await self._client.request(
             method="GET",
             uri=f"/issues/{issue_id}",
             params={"expand": expand} if expand else None,
         )
-        return self._decode(FullIssue, data)
+        return self._decode(_type, data)
 
     async def edit_issue(
         self,
         issue_id: str,
         version: str | int | None = None,
+        _type: type[IssueT_co | FullIssue] = FullIssue,
         **kwargs,
-    ) -> FullIssue:
+    ) -> IssueT_co | FullIssue:
         """Make changes to an issue.
 
         Use this request to make changes to an issue.
@@ -53,7 +61,7 @@ async def edit_issue(
             params={"version": str(version)} if version else None,
             payload=self._prepare_payload(kwargs),
         )
-        return self._decode(FullIssue, data)
+        return self._decode(_type, data)
 
     # ruff: noqa: ARG002 PLR0913
     async def create_issue(
@@ -70,8 +78,9 @@ async def create_issue(
         assignee: list[str] | None = None,
         unique: str | None = None,
         attachment_ids: list[str] | None = None,
+        _type: type[IssueT_co | FullIssue] = FullIssue,
         **kwargs,
-    ) -> FullIssue:
+    ) -> IssueT_co | FullIssue:
         """Create an issue.
 
         Source:
@@ -83,7 +92,7 @@ async def create_issue(
             uri="/issues/",
             payload=payload,
         )
-        return self._decode(FullIssue, data)
+        return self._decode(_type, data)
 
     async def move_issue(
         self,
@@ -95,8 +104,9 @@ async def move_issue(
         move_all_fields: bool = False,
         initial_status: bool = False,
         expand: str | None = None,
+        _type: type[IssueT_co | FullIssue] = FullIssue,
         **kwargs,
-    ) -> FullIssue:
+    ) -> IssueT_co | FullIssue:
         """Move an issue to a different queue.
 
         Before executing the request, make sure the user has permission
@@ -148,7 +158,7 @@ async def move_issue(
             params=params,
             payload=self._prepare_payload(kwargs),
         )
-        return self._decode(FullIssue, data)
+        return self._decode(_type, data)
 
     async def count_issues(
         self,
@@ -181,7 +191,8 @@ async def find_issues(
         expand: str | None = None,
         keys: str | None = None,
         queue: str | None = None,
-    ) -> list[FullIssue]:
+        _type: type[IssueT_co | FullIssue] = FullIssue,
+    ) -> list[IssueT_co] | list[FullIssue]:
         """Find issues.
 
         Use this request to get a list of issues that meet specific criteria.
@@ -202,9 +213,13 @@ async def find_issues(
             params=params,
             payload=payload,
         )
-        return self._decode(list[FullIssue], data)
+        return self._decode(list[_type], data)  # type: ignore[valid-type]
 
-    async def get_issue_links(self, issue_id: str) -> list[FullIssue]:
+    async def get_issue_links(
+        self,
+        issue_id: str,
+        _type: type[IssueT_co | FullIssue] = FullIssue,
+    ) -> list[IssueT_co] | list[FullIssue]:
         """Get issue links.
 
         Use this request to get information about links between issues.
@@ -214,7 +229,7 @@ async def get_issue_links(self, issue_id: str) -> list[FullIssue]:
             method="GET",
             uri=f"/issues/{issue_id}/links",
         )
-        return self._decode(list[FullIssue], data)
+        return self._decode(list[_type], data)  # type: ignore[valid-type]
 
     async def get_transitions(self, issue_id: str) -> Transitions:
         """Get transitions.

yatracker/types/__init__.py

@@ -1,7 +1,9 @@
 __all__ = [
     "Attachment",
+    "Base",
     "Comment",
     "Duration",
+    "field",
     "FullIssue",
     "Issue",
     "IssueType",
@@ -16,6 +18,7 @@
 ]
 
 from .attachment import Attachment
+from .base import Base, field
 from .comment import Comment
 from .duration import Duration
 from .full_issue import FullIssue