megaplan-sdk 0.2.0__tar.gz → 0.2.1__tar.gz

{megaplan_sdk-0.2.0/src/megaplan_sdk.egg-info → megaplan_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: megaplan-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Professional Python SDK for Megaplan API v3
 Author-email: Maxim Borzov <max@borzov.com>
 License-Expression: MIT
@@ -74,6 +74,7 @@ Dynamic: license-file
 - [Автоматическая подгрузка связанных сущностей](#автоматическая-подгрузка-связанных-сущностей)
 - [Работа с фильтрами](#работа-с-фильтрами)
 - [Настройка HTTP-клиента](#настройка-http-клиента)
+- [Работа через прокси](#работа-через-прокси)
 - [Ручное управление токенами](#ручное-управление-токенами)
 
 ### Справочная информация
@@ -570,6 +571,53 @@ actual_subtasks = await client.tasks.get_actual_sub_tasks(
 # Возвращает: list[Task] - список актуальных подзадач
 ```
 
+### Получение доступных родителей
+
+Методы для получения доступных надзадач и надпроектов (для выбора родителя при создании или перемещении задачи):
+
+```python
+# Глобальный поиск доступных родителей для новой задачи
+# Возвращает список Task и Project объектов
+parents = await client.tasks.get_available_parents(
+    is_template=False,                        # bool: Фильтр по шаблонам
+    limit=10,                                 # int: Количество элементов
+)
+for parent in parents:
+    print(f"{type(parent).__name__}: {parent.name}")  # "Task: ..." или "Project: ..."
+
+# Доступные родители для существующей задачи
+# Исключает саму задачу и её потомков
+parents = await client.tasks.get_available_parents_for(
+    task_id=123,
+    is_template=False,
+    limit=10,
+)
+```
+
+**Примечание:** Методы возвращают смешанный список объектов `Task` и `Project`, так как задача может быть вложена как в другую задачу, так и в проект.
+
+### Получение всех участников задачи
+
+Метод `get_all_participants()` возвращает полный список участников задачи (ответственный, соисполнители, аудиторы, владелец) в одном запросе:
+
+```python
+participants = await client.tasks.get_all_participants(
+    task_id=123,
+    limit=None,                               # int: Количество элементов
+    # ... стандартные параметры пагинации
+)
+# Возвращает: list[Employee | ContractorHuman | Group]
+
+for participant in participants:
+    if hasattr(participant, 'display_name'):
+        print(participant.display_name())
+```
+
+**Типы участников:**
+- `Employee` — сотрудник организации
+- `ContractorHuman` — контрагент-физлицо
+- `Group` — группа участников (например, отдел)
+
 ### Получение задач на уровне дерева
 
 ```python
@@ -790,6 +838,45 @@ actual_issues = await client.projects.get_actual_issues(
 # Возвращает: list[Task] - список актуальных задач проекта
 ```
 
+### Получение доступных родителей
+
+Методы для получения доступных родительских проектов (для выбора родителя при создании или перемещении проекта):
+
+```python
+# Глобальный поиск доступных родительских проектов
+parents = await client.projects.get_available_parents(
+    is_template=False,                        # bool: Фильтр по шаблонам
+    limit=10,                                 # int: Количество элементов
+)
+for parent in parents:
+    print(f"Project: {parent.name}")
+
+# Доступные родители для существующего проекта
+# Исключает сам проект и его потомков
+parents = await client.projects.get_available_parents_for(
+    project_id=456,
+    is_template=False,
+    limit=10,
+)
+```
+
+**Примечание:** В отличие от задач, проекты могут быть вложены только в другие проекты, поэтому возвращается список объектов `Project`.
+
+### Получение всех участников проекта
+
+Метод `get_all_participants()` возвращает полный список участников проекта в одном запросе:
+
+```python
+participants = await client.projects.get_all_participants(
+    project_id=123,
+    limit=None,                               # int: Количество элементов
+)
+# Возвращает: list[Employee | ContractorHuman | Group]
+
+for participant in participants:
+    print(f"{type(participant).__name__}: {participant.display_name()}")
+```
+
 ### Получение полной информации о проекте
 
 Метод `get_full_details()` для проектов поддерживает следующие специфичные параметры:
@@ -917,6 +1004,23 @@ deal = await client.deals.apply_trigger(
 # Возвращает: Deal - обновленная сделка
 ```
 
+### Получение всех участников сделки
+
+Метод `get_all_participants()` возвращает полный список участников сделки:
+
+```python
+participants = await client.deals.get_all_participants(
+    deal_id=200,
+    limit=None,                               # int: Количество элементов
+)
+# Возвращает: list[Employee]
+
+for employee in participants:
+    print(employee.display_name())
+```
+
+**Примечание:** В отличие от задач и проектов, сделки возвращают только сотрудников (`Employee`).
+
 ### Получение аудиторов сделки
 
 ```python
@@ -1402,6 +1506,48 @@ client = MegaplanClient(
 )
 ```
 
+### Работа через прокси
+
+SDK поддерживает работу через HTTP/HTTPS/SOCKS5 прокси-серверы. Это полезно для корпоративных сетей, где все запросы должны проходить через прокси.
+
+```python
+# HTTP прокси с аутентификацией
+async with MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    username="user@example.com",
+    password="password",
+    proxy="http://login:pass@proxy.corp.local:8080",
+) as client:
+    tasks = await client.tasks.list()
+
+# HTTP прокси без аутентификации
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="http://proxy.corp.local:8080",
+)
+
+# HTTPS прокси
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="https://proxy.corp.local:8080",
+)
+
+# SOCKS5 прокси (требует httpx[socks])
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="socks5://user:pass@proxy.corp.local:1080",
+)
+```
+
+**Поддерживаемые форматы прокси:**
+- `http://proxy:port` - HTTP прокси без аутентификации
+- `http://user:password@proxy:port` - HTTP прокси с аутентификацией
+- `https://proxy:port` - HTTPS прокси
+- `socks5://user:password@proxy:port` - SOCKS5 прокси (требует `pip install httpx[socks]`)
+
 ### Ручное управление токенами
 
 ```python
@@ -1440,13 +1586,39 @@ API возвращает ошибку 500 при попытке получить
 # comments = await client.contractors.get_comments(contractor_id=123)
 
 # Вместо этого используйте комментарии в сделках контрагента
-deals = await client.deals.list(
-    base_on={"contentType": "Contractor", "id": 123}
-)
+deals = await client.contractors.get_deals(contractor_id=123)
 for deal in deals:
     comments = await client.deals.get_comments(deal.id)
 ```
 
+### Получение сделок контрагента
+
+SDK предоставляет удобный метод `get_deals()` для получения сделок контрагента:
+
+```python
+# Получить все сделки контрагента
+deals = await client.contractors.get_deals(
+    contractor_id=123,
+    limit=50  # Опционально
+)
+
+for deal in deals:
+    print(f"[{deal.id}] {deal.name}")
+    if deal.state:
+        print(f"  Статус: {deal.state}")
+```
+
+Это удобнее, чем использование `FilterBuilder`:
+
+```python
+# Альтернатива через FilterBuilder (более сложный способ)
+from megaplan_sdk import TradeFilterBuilder
+filter_obj = TradeFilterBuilder().field("contractor").equals(
+    {"contentType": "Contractor", "id": 123}
+).build()
+deals = await client.deals.list(filter=filter_obj)
+```
+
 ### Поиск сотрудников
 
 Поиск сотрудников по имени или телефону может работать некорректно и возвращать 0 результатов. Для надежного поиска используйте точный email:

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/README.md

@@ -42,6 +42,7 @@
 - [Автоматическая подгрузка связанных сущностей](#автоматическая-подгрузка-связанных-сущностей)
 - [Работа с фильтрами](#работа-с-фильтрами)
 - [Настройка HTTP-клиента](#настройка-http-клиента)
+- [Работа через прокси](#работа-через-прокси)
 - [Ручное управление токенами](#ручное-управление-токенами)
 
 ### Справочная информация
@@ -538,6 +539,53 @@ actual_subtasks = await client.tasks.get_actual_sub_tasks(
 # Возвращает: list[Task] - список актуальных подзадач
 ```
 
+### Получение доступных родителей
+
+Методы для получения доступных надзадач и надпроектов (для выбора родителя при создании или перемещении задачи):
+
+```python
+# Глобальный поиск доступных родителей для новой задачи
+# Возвращает список Task и Project объектов
+parents = await client.tasks.get_available_parents(
+    is_template=False,                        # bool: Фильтр по шаблонам
+    limit=10,                                 # int: Количество элементов
+)
+for parent in parents:
+    print(f"{type(parent).__name__}: {parent.name}")  # "Task: ..." или "Project: ..."
+
+# Доступные родители для существующей задачи
+# Исключает саму задачу и её потомков
+parents = await client.tasks.get_available_parents_for(
+    task_id=123,
+    is_template=False,
+    limit=10,
+)
+```
+
+**Примечание:** Методы возвращают смешанный список объектов `Task` и `Project`, так как задача может быть вложена как в другую задачу, так и в проект.
+
+### Получение всех участников задачи
+
+Метод `get_all_participants()` возвращает полный список участников задачи (ответственный, соисполнители, аудиторы, владелец) в одном запросе:
+
+```python
+participants = await client.tasks.get_all_participants(
+    task_id=123,
+    limit=None,                               # int: Количество элементов
+    # ... стандартные параметры пагинации
+)
+# Возвращает: list[Employee | ContractorHuman | Group]
+
+for participant in participants:
+    if hasattr(participant, 'display_name'):
+        print(participant.display_name())
+```
+
+**Типы участников:**
+- `Employee` — сотрудник организации
+- `ContractorHuman` — контрагент-физлицо
+- `Group` — группа участников (например, отдел)
+
 ### Получение задач на уровне дерева
 
 ```python
@@ -758,6 +806,45 @@ actual_issues = await client.projects.get_actual_issues(
 # Возвращает: list[Task] - список актуальных задач проекта
 ```
 
+### Получение доступных родителей
+
+Методы для получения доступных родительских проектов (для выбора родителя при создании или перемещении проекта):
+
+```python
+# Глобальный поиск доступных родительских проектов
+parents = await client.projects.get_available_parents(
+    is_template=False,                        # bool: Фильтр по шаблонам
+    limit=10,                                 # int: Количество элементов
+)
+for parent in parents:
+    print(f"Project: {parent.name}")
+
+# Доступные родители для существующего проекта
+# Исключает сам проект и его потомков
+parents = await client.projects.get_available_parents_for(
+    project_id=456,
+    is_template=False,
+    limit=10,
+)
+```
+
+**Примечание:** В отличие от задач, проекты могут быть вложены только в другие проекты, поэтому возвращается список объектов `Project`.
+
+### Получение всех участников проекта
+
+Метод `get_all_participants()` возвращает полный список участников проекта в одном запросе:
+
+```python
+participants = await client.projects.get_all_participants(
+    project_id=123,
+    limit=None,                               # int: Количество элементов
+)
+# Возвращает: list[Employee | ContractorHuman | Group]
+
+for participant in participants:
+    print(f"{type(participant).__name__}: {participant.display_name()}")
+```
+
 ### Получение полной информации о проекте
 
 Метод `get_full_details()` для проектов поддерживает следующие специфичные параметры:
@@ -885,6 +972,23 @@ deal = await client.deals.apply_trigger(
 # Возвращает: Deal - обновленная сделка
 ```
 
+### Получение всех участников сделки
+
+Метод `get_all_participants()` возвращает полный список участников сделки:
+
+```python
+participants = await client.deals.get_all_participants(
+    deal_id=200,
+    limit=None,                               # int: Количество элементов
+)
+# Возвращает: list[Employee]
+
+for employee in participants:
+    print(employee.display_name())
+```
+
+**Примечание:** В отличие от задач и проектов, сделки возвращают только сотрудников (`Employee`).
+
 ### Получение аудиторов сделки
 
 ```python
@@ -1370,6 +1474,48 @@ client = MegaplanClient(
 )
 ```
 
+### Работа через прокси
+
+SDK поддерживает работу через HTTP/HTTPS/SOCKS5 прокси-серверы. Это полезно для корпоративных сетей, где все запросы должны проходить через прокси.
+
+```python
+# HTTP прокси с аутентификацией
+async with MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    username="user@example.com",
+    password="password",
+    proxy="http://login:pass@proxy.corp.local:8080",
+) as client:
+    tasks = await client.tasks.list()
+
+# HTTP прокси без аутентификации
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="http://proxy.corp.local:8080",
+)
+
+# HTTPS прокси
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="https://proxy.corp.local:8080",
+)
+
+# SOCKS5 прокси (требует httpx[socks])
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="socks5://user:pass@proxy.corp.local:1080",
+)
+```
+
+**Поддерживаемые форматы прокси:**
+- `http://proxy:port` - HTTP прокси без аутентификации
+- `http://user:password@proxy:port` - HTTP прокси с аутентификацией
+- `https://proxy:port` - HTTPS прокси
+- `socks5://user:password@proxy:port` - SOCKS5 прокси (требует `pip install httpx[socks]`)
+
 ### Ручное управление токенами
 
 ```python
@@ -1408,13 +1554,39 @@ API возвращает ошибку 500 при попытке получить
 # comments = await client.contractors.get_comments(contractor_id=123)
 
 # Вместо этого используйте комментарии в сделках контрагента
-deals = await client.deals.list(
-    base_on={"contentType": "Contractor", "id": 123}
-)
+deals = await client.contractors.get_deals(contractor_id=123)
 for deal in deals:
     comments = await client.deals.get_comments(deal.id)
 ```
 
+### Получение сделок контрагента
+
+SDK предоставляет удобный метод `get_deals()` для получения сделок контрагента:
+
+```python
+# Получить все сделки контрагента
+deals = await client.contractors.get_deals(
+    contractor_id=123,
+    limit=50  # Опционально
+)
+
+for deal in deals:
+    print(f"[{deal.id}] {deal.name}")
+    if deal.state:
+        print(f"  Статус: {deal.state}")
+```
+
+Это удобнее, чем использование `FilterBuilder`:
+
+```python
+# Альтернатива через FilterBuilder (более сложный способ)
+from megaplan_sdk import TradeFilterBuilder
+filter_obj = TradeFilterBuilder().field("contractor").equals(
+    {"contentType": "Contractor", "id": 123}
+).build()
+deals = await client.deals.list(filter=filter_obj)
+```
+
 ### Поиск сотрудников
 
 Поиск сотрудников по имени или телефону может работать некорректно и возвращать 0 результатов. Для надежного поиска используйте точный email:

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "megaplan-sdk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Professional Python SDK for Megaplan API v3"
 readme = "README.md"
 requires-python = ">=3.11"

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/src/megaplan_sdk/__init__.py

@@ -40,7 +40,9 @@ from megaplan_sdk.models.filter import (
     TradeFilter,
     UserSetting,
 )
+from megaplan_sdk.models.group import Group
 from megaplan_sdk.models.milestone import Milestone
+from megaplan_sdk.models.participant import Participant, parse_participant, parse_participants
 from megaplan_sdk.models.project import Project, ProjectFullDetails
 from megaplan_sdk.models.task import Task, TaskFullDetails
 from megaplan_sdk.resources.filters import FiltersResource
@@ -69,7 +71,11 @@ __all__ = [
     "ContractorHuman",
     "Employee",
     "Department",
+    "Group",
     "Milestone",
+    "Participant",
+    "parse_participant",
+    "parse_participants",
     "DateTime",
     # Filters
     "FiltersResource",

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/src/megaplan_sdk/client.py

@@ -38,6 +38,7 @@ class MegaplanClient:
         cache_max_size: int = 1000,
         default_comments_limit: int | None = None,
         default_history_limit: int | None = None,
+        proxy: str | None = None,
     ) -> None:
         """Initialize Megaplan client.
 
@@ -60,6 +61,8 @@ class MegaplanClient:
             default_history_limit: Default limit for history in get_full_details().
                 None = use Megaplan API default (no explicit limit).
                 This value is used only if history_limit is not specified in method call.
+            proxy: Proxy URL for HTTP requests (e.g., http://user:pass@proxy:8080).
+                Supports HTTP, HTTPS, and SOCKS5 proxies.
 
         Security Note:
             For production use, it's recommended to use refresh tokens or pre-obtained
@@ -78,6 +81,7 @@ class MegaplanClient:
             timeout=timeout,
             max_retries=max_retries,
             allow_http=allow_http,
+            proxy=proxy,
         )
         self._auth_manager = AuthManager(self._http)
 

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/src/megaplan_sdk/constants.py

@@ -14,3 +14,4 @@ class ContentType:
     CONTRACTOR_CATEGORY = "ContractorCategory"
     DEPARTMENT = "Department"
     COMMENT = "Comment"
+    GROUP = "Group"

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/src/megaplan_sdk/http_client.py

@@ -28,6 +28,7 @@ class HTTPClient:
         timeout: float = 30.0,
         max_retries: int = 3,
         allow_http: bool = False,
+        proxy: str | None = None,
     ) -> None:
         """Initialize HTTP client.
 
@@ -37,6 +38,8 @@ class HTTPClient:
             timeout: Request timeout in seconds.
             max_retries: Maximum number of retry attempts for 5xx errors.
             allow_http: Allow HTTP connections (insecure, only for dev/test).
+            proxy: Proxy URL for HTTP requests (e.g., http://user:pass@proxy:8080).
+                Supports HTTP, HTTPS, and SOCKS5 proxies.
 
         Raises:
             ValueError: If base_url is not HTTPS and allow_http is False.
@@ -52,6 +55,7 @@ class HTTPClient:
         self._access_token: str | None = access_token
         self.timeout = timeout
         self.max_retries = max_retries
+        self._proxy = proxy
         self._client: httpx.AsyncClient | None = None
 
     @property
@@ -83,7 +87,8 @@ class HTTPClient:
                 timeout=self.timeout,
                 headers={"Content-Type": "application/json"},
                 limits=limits,
-                follow_redirects=True,  # Follow redirects automatically
+                follow_redirects=True,
+                proxy=self._proxy,
             )
 
     async def close(self) -> None:

{megaplan_sdk-0.2.0 → megaplan_sdk-0.2.1}/src/megaplan_sdk/models/__init__.py

@@ -3,6 +3,8 @@
 from megaplan_sdk.models.base import BaseEntity
 from megaplan_sdk.models.common import File, Meta, Pagination, SortField
 from megaplan_sdk.models.deal import Deal, ProgramState, TradeFilter
+from megaplan_sdk.models.group import Group
+from megaplan_sdk.models.participant import Participant, parse_participant, parse_participants
 from megaplan_sdk.models.project import Project, ProjectFilter
 from megaplan_sdk.models.task import Task, TaskFilter
 
@@ -19,4 +21,8 @@ __all__ = [
     "Deal",
     "TradeFilter",
     "ProgramState",
+    "Group",
+    "Participant",
+    "parse_participant",
+    "parse_participants",
 ]

megaplan_sdk-0.2.1/src/megaplan_sdk/models/group.py

@@ -0,0 +1,40 @@
+"""Group model for Megaplan SDK."""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from megaplan_sdk.models.base import BaseEntity
+
+
+class Group(BaseEntity):
+    """Group entity for organizing participants.
+
+    Used to group entities by some attribute (e.g., department, role).
+
+    Attributes:
+        id: Group identifier.
+        content_type: Entity content type (always "Group").
+        name: Group name.
+        children: List of child entities in this group.
+        children_count: Number of entities in this group.
+    """
+
+    content_type: str = Field(alias="contentType", default="Group")
+    name: str | None = None
+    children: list[BaseEntity] | None = None
+    children_count: int | None = Field(alias="childrenCount", default=None)
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    def display_name(self) -> str:
+        """Get display name for the group.
+
+        Returns:
+            Group name or fallback identifier.
+        """
+        return self.name or f"Group#{self.id}"
+
+    def __str__(self) -> str:
+        """Return display name for string representation."""
+        return self.display_name()

megaplan_sdk-0.2.1/src/megaplan_sdk/models/participant.py

@@ -0,0 +1,74 @@
+"""Participant types for Megaplan SDK.
+
+This module provides union types and parsing utilities for participant entities
+returned by allParticipants endpoints.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from megaplan_sdk.constants import ContentType
+from megaplan_sdk.models.contractor import ContractorHuman
+from megaplan_sdk.models.employee import Employee
+from megaplan_sdk.models.group import Group
+
+Participant = Employee | ContractorHuman | Group
+"""Union type for participants in tasks and projects.
+
+Participants can be:
+- Employee: An employee of the organization
+- ContractorHuman: A human contractor (individual)
+- Group: A group of participants (e.g., department)
+"""
+
+
+def parse_participant(data: dict[str, Any]) -> Participant:
+    """Parse participant data into appropriate model based on contentType.
+
+    Args:
+        data: Raw participant data from API response.
+
+    Returns:
+        Parsed participant as Employee, ContractorHuman, or Group.
+
+    Raises:
+        ValueError: If contentType is unknown or missing.
+
+    Examples:
+        >>> data = {"contentType": "Employee", "id": 123, "firstName": "John"}
+        >>> participant = parse_participant(data)
+        >>> isinstance(participant, Employee)
+        True
+    """
+    content_type = data.get("contentType")
+
+    if content_type == ContentType.EMPLOYEE:
+        return Employee(**data)
+    elif content_type == ContentType.CONTRACTOR_HUMAN:
+        return ContractorHuman(**data)
+    elif content_type == ContentType.GROUP:
+        return Group(**data)
+    else:
+        raise ValueError(f"Unknown participant contentType: {content_type}")
+
+
+def parse_participants(data_list: list[dict[str, Any]]) -> list[Participant]:
+    """Parse list of participant data into appropriate models.
+
+    Args:
+        data_list: List of raw participant data from API response.
+
+    Returns:
+        List of parsed participants.
+
+    Examples:
+        >>> data = [
+        ...     {"contentType": "Employee", "id": 1, "firstName": "John"},
+        ...     {"contentType": "Group", "id": 2, "name": "Developers"},
+        ... ]
+        >>> participants = parse_participants(data)
+        >>> len(participants)
+        2
+    """
+    return [parse_participant(item) for item in data_list]