mcp-ticketer 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

mcp_ticketer/core/config.py

@@ -6,7 +6,7 @@ import os
 from enum import Enum
 from functools import lru_cache
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -27,23 +27,23 @@ class BaseAdapterConfig(BaseModel):
     """Base configuration for all adapters."""
 
     type: AdapterType
-    name: Optional[str] = None
+    name: str | None = None
     enabled: bool = True
     timeout: float = 30.0
     max_retries: int = 3
-    rate_limit: Optional[dict[str, Any]] = None
+    rate_limit: dict[str, Any] | None = None
 
 
 class GitHubConfig(BaseAdapterConfig):
     """GitHub adapter configuration."""
 
     type: AdapterType = AdapterType.GITHUB
-    token: Optional[str] = Field(None, env="GITHUB_TOKEN")
-    owner: Optional[str] = Field(None, env="GITHUB_OWNER")
-    repo: Optional[str] = Field(None, env="GITHUB_REPO")
+    token: str | None = Field(None, env="GITHUB_TOKEN")
+    owner: str | None = Field(None, env="GITHUB_OWNER")
+    repo: str | None = Field(None, env="GITHUB_REPO")
     api_url: str = "https://api.github.com"
     use_projects_v2: bool = False
-    custom_priority_scheme: Optional[dict[str, list[str]]] = None
+    custom_priority_scheme: dict[str, list[str]] | None = None
 
     @field_validator("token", mode="before")
     @classmethod
@@ -77,10 +77,10 @@ class JiraConfig(BaseAdapterConfig):
     """JIRA adapter configuration."""
 
     type: AdapterType = AdapterType.JIRA
-    server: Optional[str] = Field(None, env="JIRA_SERVER")
-    email: Optional[str] = Field(None, env="JIRA_EMAIL")
-    api_token: Optional[str] = Field(None, env="JIRA_API_TOKEN")
-    project_key: Optional[str] = Field(None, env="JIRA_PROJECT_KEY")
+    server: str | None = Field(None, env="JIRA_SERVER")
+    email: str | None = Field(None, env="JIRA_EMAIL")
+    api_token: str | None = Field(None, env="JIRA_API_TOKEN")
+    project_key: str | None = Field(None, env="JIRA_PROJECT_KEY")
     cloud: bool = True
     verify_ssl: bool = True
 
@@ -116,10 +116,10 @@ class LinearConfig(BaseAdapterConfig):
     """Linear adapter configuration."""
 
     type: AdapterType = AdapterType.LINEAR
-    api_key: Optional[str] = Field(None, env="LINEAR_API_KEY")
-    workspace: Optional[str] = None
-    team_key: Optional[str] = None  # Short team key like "BTA"
-    team_id: Optional[str] = None  # UUID team identifier
+    api_key: str | None = Field(None, env="LINEAR_API_KEY")
+    workspace: str | None = None
+    team_key: str | None = None  # Short team key like "BTA"
+    team_id: str | None = None  # UUID team identifier
     api_url: str = "https://api.linear.app/graphql"
 
     @model_validator(mode="after")
@@ -150,7 +150,7 @@ class QueueConfig(BaseModel):
     """Queue configuration."""
 
     provider: str = "sqlite"
-    connection_string: Optional[str] = None
+    connection_string: str | None = None
     batch_size: int = 10
     max_concurrent: int = 5
     retry_attempts: int = 3
@@ -162,7 +162,7 @@ class LoggingConfig(BaseModel):
 
     level: str = "INFO"
     format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    file: Optional[str] = None
+    file: str | None = None
     max_size: str = "10MB"
     backup_count: int = 5
 
@@ -171,12 +171,12 @@ class AppConfig(BaseModel):
     """Main application configuration."""
 
     adapters: dict[
-        str, Union[GitHubConfig, JiraConfig, LinearConfig, AITrackdownConfig]
+        str, GitHubConfig | JiraConfig | LinearConfig | AITrackdownConfig
     ] = {}
     queue: QueueConfig = QueueConfig()
     logging: LoggingConfig = LoggingConfig()
     cache_ttl: int = 300  # Cache TTL in seconds
-    default_adapter: Optional[str] = None
+    default_adapter: str | None = None
 
     @model_validator(mode="after")
     def validate_adapters(self):
@@ -196,7 +196,7 @@ class AppConfig(BaseModel):
 
         return self
 
-    def get_adapter_config(self, adapter_name: str) -> Optional[BaseAdapterConfig]:
+    def get_adapter_config(self, adapter_name: str) -> BaseAdapterConfig | None:
         """Get configuration for a specific adapter."""
         return self.adapters.get(adapter_name)
 
@@ -211,7 +211,7 @@ class ConfigurationManager:
     """Centralized configuration management with caching and validation."""
 
     _instance: Optional["ConfigurationManager"] = None
-    _config: Optional[AppConfig] = None
+    _config: AppConfig | None = None
     _config_file_paths: list[Path] = []
 
     def __new__(cls) -> "ConfigurationManager":
@@ -266,7 +266,7 @@ class ConfigurationManager:
             logger.debug("No project-local config files found, will use defaults")
 
     @lru_cache(maxsize=1)
-    def load_config(self, config_file: Optional[Union[str, Path]] = None) -> AppConfig:
+    def load_config(self, config_file: str | Path | None = None) -> AppConfig:
         """Load and validate configuration from file and environment.
 
         Args:
@@ -437,7 +437,7 @@ class ConfigurationManager:
             return self.load_config()
         return self._config
 
-    def get_adapter_config(self, adapter_name: str) -> Optional[BaseAdapterConfig]:
+    def get_adapter_config(self, adapter_name: str) -> BaseAdapterConfig | None:
         """Get configuration for a specific adapter."""
         config = self.get_config()
         return config.get_adapter_config(adapter_name)
@@ -457,9 +457,7 @@ class ConfigurationManager:
         config = self.get_config()
         return config.logging
 
-    def reload_config(
-        self, config_file: Optional[Union[str, Path]] = None
-    ) -> AppConfig:
+    def reload_config(self, config_file: str | Path | None = None) -> AppConfig:
         """Reload configuration from file."""
         # Clear cache
         self.load_config.cache_clear()
@@ -492,7 +490,7 @@ class ConfigurationManager:
         self._config_cache[key] = value
         return value
 
-    def create_sample_config(self, output_path: Union[str, Path]) -> None:
+    def create_sample_config(self, output_path: str | Path) -> None:
         """Create a sample configuration file."""
         sample_config = {
             "adapters": {
@@ -539,11 +537,11 @@ def get_config() -> AppConfig:
     return config_manager.get_config()
 
 
-def get_adapter_config(adapter_name: str) -> Optional[BaseAdapterConfig]:
+def get_adapter_config(adapter_name: str) -> BaseAdapterConfig | None:
     """Get configuration for a specific adapter."""
     return config_manager.get_adapter_config(adapter_name)
 
 
-def reload_config(config_file: Optional[Union[str, Path]] = None) -> AppConfig:
+def reload_config(config_file: str | Path | None = None) -> AppConfig:
     """Reload the global configuration."""
     return config_manager.reload_config(config_file)

mcp_ticketer/core/env_discovery.py

@@ -11,7 +11,7 @@ environment files, including:
 import logging
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from dotenv import dotenv_values
 
@@ -125,7 +125,7 @@ class DiscoveryResult:
     warnings: list[str] = field(default_factory=list)
     env_files_found: list[str] = field(default_factory=list)
 
-    def get_primary_adapter(self) -> Optional[DiscoveredAdapter]:
+    def get_primary_adapter(self) -> DiscoveredAdapter | None:
         """Get the adapter with highest confidence and completeness."""
         if not self.adapters:
             return None
@@ -136,7 +136,7 @@ class DiscoveryResult:
         )
         return sorted_adapters[0]
 
-    def get_adapter_by_type(self, adapter_type: str) -> Optional[DiscoveredAdapter]:
+    def get_adapter_by_type(self, adapter_type: str) -> DiscoveredAdapter | None:
         """Get discovered adapter by type."""
         for adapter in self.adapters:
             if adapter.adapter_type == adapter_type:
@@ -155,7 +155,7 @@ class EnvDiscovery:
         ".env.development",
     ]
 
-    def __init__(self, project_path: Optional[Path] = None):
+    def __init__(self, project_path: Path | None = None):
         """Initialize discovery.
 
         Args:
@@ -255,7 +255,7 @@ class EnvDiscovery:
 
     def _find_key_value(
         self, env_vars: dict[str, str], patterns: list[str]
-    ) -> Optional[str]:
+    ) -> str | None:
         """Find first matching key value from patterns.
 
         Args:
@@ -273,7 +273,7 @@ class EnvDiscovery:
 
     def _detect_linear(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect Linear adapter configuration.
 
         Args:
@@ -327,7 +327,7 @@ class EnvDiscovery:
 
     def _detect_github(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect GitHub adapter configuration.
 
         Args:
@@ -386,7 +386,7 @@ class EnvDiscovery:
 
     def _detect_jira(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect JIRA adapter configuration.
 
         Args:
@@ -442,7 +442,7 @@ class EnvDiscovery:
 
     def _detect_aitrackdown(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect AITrackdown adapter configuration.
 
         Args:
@@ -622,7 +622,7 @@ class EnvDiscovery:
         return warnings
 
 
-def discover_config(project_path: Optional[Path] = None) -> DiscoveryResult:
+def discover_config(project_path: Path | None = None) -> DiscoveryResult:
     """Convenience function to discover configuration.
 
     Args:

mcp_ticketer/core/env_loader.py

@@ -12,7 +12,7 @@ import logging
 import os
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -25,7 +25,7 @@ class EnvKeyConfig:
     aliases: list[str]
     description: str
     required: bool = False
-    default: Optional[str] = None
+    default: str | None = None
 
 
 class UnifiedEnvLoader:
@@ -105,7 +105,7 @@ class UnifiedEnvLoader:
         ),
     }
 
-    def __init__(self, project_root: Optional[Path] = None):
+    def __init__(self, project_root: Path | None = None):
         """Initialize the environment loader.
 
         Args:
@@ -177,8 +177,8 @@ class UnifiedEnvLoader:
             logger.warning(f"Failed to load {env_file}: {e}")
 
     def get_value(
-        self, config_key: str, config: Optional[dict[str, Any]] = None
-    ) -> Optional[str]:
+        self, config_key: str, config: dict[str, Any] | None = None
+    ) -> str | None:
         """Get a configuration value using the key alias system.
 
         Args:
@@ -230,7 +230,7 @@ class UnifiedEnvLoader:
         return None
 
     def get_adapter_config(
-        self, adapter_name: str, base_config: Optional[dict[str, Any]] = None
+        self, adapter_name: str, base_config: dict[str, Any] | None = None
     ) -> dict[str, Any]:
         """Get complete configuration for an adapter with environment variable resolution.
 
@@ -307,7 +307,7 @@ class UnifiedEnvLoader:
 
 
 # Global instance
-_env_loader: Optional[UnifiedEnvLoader] = None
+_env_loader: UnifiedEnvLoader | None = None
 
 
 def get_env_loader() -> UnifiedEnvLoader:
@@ -319,7 +319,7 @@ def get_env_loader() -> UnifiedEnvLoader:
 
 
 def load_adapter_config(
-    adapter_name: str, base_config: Optional[dict[str, Any]] = None
+    adapter_name: str, base_config: dict[str, Any] | None = None
 ) -> dict[str, Any]:
     """Convenience function to load adapter configuration with environment variables.
 

mcp_ticketer/core/http_client.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 import time
 from enum import Enum
-from typing import Any, Optional, Union
+from typing import Any
 
 import httpx
 from httpx import AsyncClient, TimeoutException
@@ -32,8 +32,8 @@ class RetryConfig:
         max_delay: float = 60.0,
         exponential_base: float = 2.0,
         jitter: bool = True,
-        retry_on_status: Optional[list[int]] = None,
-        retry_on_exceptions: Optional[list[type]] = None,
+        retry_on_status: list[int] | None = None,
+        retry_on_exceptions: list[type] | None = None,
     ):
         self.max_retries = max_retries
         self.initial_delay = initial_delay
@@ -94,11 +94,11 @@ class BaseHTTPClient:
     def __init__(
         self,
         base_url: str,
-        headers: Optional[dict[str, str]] = None,
-        auth: Optional[Union[httpx.Auth, tuple]] = None,
+        headers: dict[str, str] | None = None,
+        auth: httpx.Auth | tuple | None = None,
         timeout: float = 30.0,
-        retry_config: Optional[RetryConfig] = None,
-        rate_limiter: Optional[RateLimiter] = None,
+        retry_config: RetryConfig | None = None,
+        rate_limiter: RateLimiter | None = None,
         verify_ssl: bool = True,
         follow_redirects: bool = True,
     ):
@@ -132,7 +132,7 @@ class BaseHTTPClient:
             "errors": 0,
         }
 
-        self._client: Optional[AsyncClient] = None
+        self._client: AsyncClient | None = None
 
     async def _get_client(self) -> AsyncClient:
         """Get or create HTTP client instance."""
@@ -148,7 +148,7 @@ class BaseHTTPClient:
         return self._client
 
     async def _calculate_delay(
-        self, attempt: int, response: Optional[httpx.Response] = None
+        self, attempt: int, response: httpx.Response | None = None
     ) -> float:
         """Calculate delay for retry attempt."""
         if response and response.status_code == 429:
@@ -178,7 +178,7 @@ class BaseHTTPClient:
     def _should_retry(
         self,
         exception: Exception,
-        response: Optional[httpx.Response] = None,
+        response: httpx.Response | None = None,
         attempt: int = 1,
     ) -> bool:
         """Determine if request should be retried."""
@@ -198,13 +198,13 @@ class BaseHTTPClient:
 
     async def request(
         self,
-        method: Union[HTTPMethod, str],
+        method: HTTPMethod | str,
         endpoint: str,
-        data: Optional[dict[str, Any]] = None,
-        json: Optional[dict[str, Any]] = None,
-        params: Optional[dict[str, Any]] = None,
-        headers: Optional[dict[str, str]] = None,
-        timeout: Optional[float] = None,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
         retry_count: int = 0,
         **kwargs,
     ) -> httpx.Response:

mcp_ticketer/core/mappers.py

@@ -3,7 +3,7 @@
 import logging
 from abc import ABC, abstractmethod
 from functools import lru_cache
-from typing import Any, Generic, Optional, TypeVar
+from typing import Any, Generic, TypeVar
 
 from .models import Priority, TicketState
 
@@ -27,11 +27,11 @@ class BiDirectionalDict(Generic[T, U]):
         self._reverse: dict[U, T] = {v: k for k, v in mapping.items()}
         self._cache: dict[str, Any] = {}
 
-    def get_forward(self, key: T, default: Optional[U] = None) -> Optional[U]:
+    def get_forward(self, key: T, default: U | None = None) -> U | None:
         """Get value by forward key."""
         return self._forward.get(key, default)
 
-    def get_reverse(self, key: U, default: Optional[T] = None) -> Optional[T]:
+    def get_reverse(self, key: U, default: T | None = None) -> T | None:
         """Get value by reverse key."""
         return self._reverse.get(key, default)
 
@@ -83,7 +83,7 @@ class StateMapper(BaseMapper):
     """Universal state mapping utility."""
 
     def __init__(
-        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        self, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ):
         """Initialize state mapper.
 
@@ -95,7 +95,7 @@ class StateMapper(BaseMapper):
         super().__init__()
         self.adapter_type = adapter_type
         self.custom_mappings = custom_mappings or {}
-        self._mapping: Optional[BiDirectionalDict] = None
+        self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
     def get_mapping(self) -> BiDirectionalDict:
@@ -229,7 +229,7 @@ class StateMapper(BaseMapper):
         """Check if adapter uses labels for extended states."""
         return self.adapter_type in ["github", "linear"]
 
-    def get_state_label(self, state: TicketState) -> Optional[str]:
+    def get_state_label(self, state: TicketState) -> str | None:
         """Get label name for extended states that require labels.
 
         Args:
@@ -258,7 +258,7 @@ class PriorityMapper(BaseMapper):
     """Universal priority mapping utility."""
 
     def __init__(
-        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        self, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ):
         """Initialize priority mapper.
 
@@ -270,7 +270,7 @@ class PriorityMapper(BaseMapper):
         super().__init__()
         self.adapter_type = adapter_type
         self.custom_mappings = custom_mappings or {}
-        self._mapping: Optional[BiDirectionalDict] = None
+        self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
     def get_mapping(self) -> BiDirectionalDict:
@@ -483,7 +483,7 @@ class MapperRegistry:
 
     @classmethod
     def get_state_mapper(
-        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ) -> StateMapper:
         """Get or create state mapper for adapter type.
 
@@ -502,7 +502,7 @@ class MapperRegistry:
 
     @classmethod
     def get_priority_mapper(
-        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ) -> PriorityMapper:
         """Get or create priority mapper for adapter type.
 

mcp_ticketer/core/models.py

@@ -25,7 +25,7 @@ Example:
 
 from datetime import datetime
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -194,14 +194,14 @@ class BaseTicket(BaseModel):
 
     model_config = ConfigDict(use_enum_values=True)
 
-    id: Optional[str] = Field(None, description="Unique identifier")
+    id: str | None = Field(None, description="Unique identifier")
     title: str = Field(..., min_length=1, description="Ticket title")
-    description: Optional[str] = Field(None, description="Detailed description")
+    description: str | None = Field(None, description="Detailed description")
     state: TicketState = Field(TicketState.OPEN, description="Current state")
     priority: Priority = Field(Priority.MEDIUM, description="Priority level")
     tags: list[str] = Field(default_factory=list, description="Tags/labels")
-    created_at: Optional[datetime] = Field(None, description="Creation timestamp")
-    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
+    created_at: datetime | None = Field(None, description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
 
     # Metadata for field mapping to different systems
     metadata: dict[str, Any] = Field(
@@ -270,20 +270,20 @@ class Task(BaseTicket):
     ticket_type: TicketType = Field(
         default=TicketType.ISSUE, description="Ticket type in hierarchy"
     )
-    parent_issue: Optional[str] = Field(None, description="Parent issue ID (for tasks)")
-    parent_epic: Optional[str] = Field(
+    parent_issue: str | None = Field(None, description="Parent issue ID (for tasks)")
+    parent_epic: str | None = Field(
         None,
         description="Parent epic/project ID (for issues). Synonym: 'project'",
     )
-    assignee: Optional[str] = Field(None, description="Assigned user")
+    assignee: str | None = Field(None, description="Assigned user")
     children: list[str] = Field(default_factory=list, description="Child task IDs")
 
     # Additional fields common across systems
-    estimated_hours: Optional[float] = Field(None, description="Time estimate")
-    actual_hours: Optional[float] = Field(None, description="Actual time spent")
+    estimated_hours: float | None = Field(None, description="Time estimate")
+    actual_hours: float | None = Field(None, description="Actual time spent")
 
     @property
-    def project(self) -> Optional[str]:
+    def project(self) -> str | None:
         """Synonym for parent_epic.
 
         Returns:
@@ -293,7 +293,7 @@ class Task(BaseTicket):
         return self.parent_epic
 
     @project.setter
-    def project(self, value: Optional[str]) -> None:
+    def project(self, value: str | None) -> None:
         """Set parent_epic via project synonym.
 
         Args:
@@ -345,23 +345,53 @@ class Comment(BaseModel):
 
     model_config = ConfigDict(use_enum_values=True)
 
-    id: Optional[str] = Field(None, description="Comment ID")
+    id: str | None = Field(None, description="Comment ID")
     ticket_id: str = Field(..., description="Parent ticket ID")
-    author: Optional[str] = Field(None, description="Comment author")
+    author: str | None = Field(None, description="Comment author")
     content: str = Field(..., min_length=1, description="Comment text")
-    created_at: Optional[datetime] = Field(None, description="Creation timestamp")
+    created_at: datetime | None = Field(None, description="Creation timestamp")
     metadata: dict[str, Any] = Field(
         default_factory=dict, description="System-specific metadata"
     )
 
 
+class Attachment(BaseModel):
+    """File attachment metadata for tickets.
+
+    Represents a file attached to a ticket across all adapters.
+    Each adapter maps its native attachment format to this model.
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str | None = Field(None, description="Attachment unique identifier")
+    ticket_id: str = Field(..., description="Parent ticket identifier")
+    filename: str = Field(..., description="Original filename")
+    url: str | None = Field(None, description="Download URL or file path")
+    content_type: str | None = Field(
+        None, description="MIME type (e.g., 'application/pdf', 'image/png')"
+    )
+    size_bytes: int | None = Field(None, description="File size in bytes")
+    created_at: datetime | None = Field(None, description="Upload timestamp")
+    created_by: str | None = Field(None, description="User who uploaded the attachment")
+    description: str | None = Field(None, description="Attachment description or notes")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Adapter-specific attachment metadata"
+    )
+
+    def __str__(self) -> str:
+        """String representation showing filename and size."""
+        size_str = f" ({self.size_bytes} bytes)" if self.size_bytes else ""
+        return f"Attachment({self.filename}{size_str})"
+
+
 class SearchQuery(BaseModel):
     """Search query parameters."""
 
-    query: Optional[str] = Field(None, description="Text search query")
-    state: Optional[TicketState] = Field(None, description="Filter by state")
-    priority: Optional[Priority] = Field(None, description="Filter by priority")
-    tags: Optional[list[str]] = Field(None, description="Filter by tags")
-    assignee: Optional[str] = Field(None, description="Filter by assignee")
+    query: str | None = Field(None, description="Text search query")
+    state: TicketState | None = Field(None, description="Filter by state")
+    priority: Priority | None = Field(None, description="Filter by priority")
+    tags: list[str] | None = Field(None, description="Filter by tags")
+    assignee: str | None = Field(None, description="Filter by assignee")
     limit: int = Field(10, gt=0, le=100, description="Maximum results")
     offset: int = Field(0, ge=0, description="Result offset for pagination")