d365fo-client 0.1.0__py3-none-any.whl

d365fo_client/query.py

@@ -0,0 +1,162 @@
+"""OData query utilities for D365 F&O client."""
+
+from typing import Any, Dict, Optional, Union
+from urllib.parse import quote, urlencode
+
+from .models import QueryOptions
+
+
+class QueryBuilder:
+    """Utility class for building OData queries"""
+
+    @staticmethod
+    def build_query_string(options: Optional[QueryOptions] = None) -> str:
+        """Build OData query string from options
+
+        Args:
+            options: Query options to convert
+
+        Returns:
+            URL query string (with leading ? if parameters exist)
+        """
+        if not options:
+            return ""
+
+        params = QueryBuilder.build_query_params(options)
+
+        if params:
+            return "?" + urlencode(params, quote_via=quote)
+        return ""
+
+    @staticmethod
+    def build_query_params(options: Optional[QueryOptions] = None) -> dict:
+        """Build OData query parameters dict from options
+
+        Args:
+            options: Query options to convert
+
+        Returns:
+            Dictionary of query parameters
+        """
+        if not options:
+            return {}
+
+        params = {}
+
+        if options.select:
+            params["$select"] = ",".join(options.select)
+
+        if options.filter:
+            params["$filter"] = options.filter
+
+        if options.expand:
+            params["$expand"] = ",".join(options.expand)
+
+        if options.orderby:
+            params["$orderby"] = ",".join(options.orderby)
+
+        if options.top is not None:
+            params["$top"] = str(options.top)
+
+        if options.skip is not None:
+            params["$skip"] = str(options.skip)
+
+        if options.count:
+            params["$count"] = "true"
+
+        if options.search:
+            params["$search"] = options.search
+
+        return params
+
+    @staticmethod
+    def encode_key(key: Union[str, Dict[str, Any]]) -> str:
+        """Encode entity key for URL
+
+        Args:
+            key: Entity key value (string for simple keys, dict for composite keys)
+
+        Returns:
+            URL-encoded key
+        """
+        if isinstance(key, dict):
+            # Format composite key: key1=value1,key2=value2
+            key_parts = []
+            for key_name, key_value in key.items():
+                encoded_value = quote(str(key_value), safe="")
+                key_parts.append(f"{key_name}='{encoded_value}'")
+            return ",".join(key_parts)
+        else:
+            # Simple string key
+            return quote(str(key), safe="")
+
+    @staticmethod
+    def build_entity_url(
+        base_url: str,
+        entity_name: str,
+        key: Optional[Union[str, Dict[str, Any]]] = None,
+    ) -> str:
+        """Build entity URL
+
+        Args:
+            base_url: Base F&O URL
+            entity_name: Entity set name
+            key: Optional entity key (string for simple keys, dict for composite keys)
+
+        Returns:
+            Complete entity URL
+        """
+        base = f"{base_url.rstrip('/')}/data/{entity_name}"
+        if key:
+            encoded_key = QueryBuilder.encode_key(key)
+            if isinstance(key, dict):
+                # For composite keys, don't wrap in additional quotes
+                return f"{base}({encoded_key})"
+            else:
+                # For simple string keys, wrap in quotes
+                return f"{base}('{encoded_key}')"
+        return base
+
+    @staticmethod
+    def build_action_url(
+        base_url: str,
+        action_name: str,
+        entity_name: Optional[str] = None,
+        entity_key: Optional[Union[str, Dict[str, Any]]] = None,
+    ) -> str:
+        """Build action URL
+
+        Args:
+            base_url: Base F&O URL
+            action_name: Action name
+            entity_name: Optional entity name for bound actions
+            entity_key: Optional entity key for bound actions (string for simple keys, dict for composite keys)
+
+        Returns:
+            Complete action URL
+        """
+        base = base_url.rstrip("/")
+
+        # Ensure action_name is properly prefixed
+        if action_name.startswith("/Microsoft.Dynamics.DataEntities."):
+            action_path = action_name
+        elif action_name.startswith("Microsoft.Dynamics.DataEntities."):
+            action_path = "/" + action_name
+        else:
+            action_path = "/Microsoft.Dynamics.DataEntities." + action_name
+
+        if entity_name and entity_key:
+            # Bound action on specific entity
+            encoded_key = QueryBuilder.encode_key(entity_key)
+            if isinstance(entity_key, dict):
+                # For composite keys, don't wrap in additional quotes
+                return f"{base}/data/{entity_name}({encoded_key}){action_path}"
+            else:
+                # For simple string keys, wrap in quotes
+                return f"{base}/data/{entity_name}('{encoded_key}'){action_path}"
+        elif entity_name:
+            # Bound action on entity set
+            return f"{base}/data/{entity_name}{action_path}"
+        else:
+            # Unbound action
+            return f"{base}/data{action_path}"

d365fo_client/session.py

@@ -0,0 +1,60 @@
+"""HTTP session management for D365 F&O client."""
+
+from typing import Optional
+
+import aiohttp
+
+from .auth import AuthenticationManager
+from .models import FOClientConfig
+
+
+class SessionManager:
+    """Manages HTTP sessions with authentication"""
+
+    def __init__(self, config: FOClientConfig, auth_manager: AuthenticationManager):
+        """Initialize session manager
+
+        Args:
+            config: F&O client configuration
+            auth_manager: Authentication manager instance
+        """
+        self.config = config
+        self.auth_manager = auth_manager
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def get_session(self) -> aiohttp.ClientSession:
+        """Get HTTP session with auth headers
+
+        Returns:
+            Configured aiohttp ClientSession
+        """
+        if self._session is None or self._session.closed:
+            connector = aiohttp.TCPConnector(ssl=self.config.verify_ssl)
+            timeout = aiohttp.ClientTimeout(total=self.config.timeout)
+            self._session = aiohttp.ClientSession(connector=connector, timeout=timeout)
+
+        # Update headers with fresh token
+        token = await self.auth_manager.get_token()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+        return self._session
+
+    async def close(self):
+        """Close the HTTP session"""
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit"""
+        await self.close()

d365fo_client/utils.py

@@ -0,0 +1,196 @@
+"""Utility functions for D365 F&O client."""
+
+import os
+import platform
+import re
+from pathlib import Path
+from typing import Union
+from urllib.parse import urlparse
+
+
+def get_user_cache_dir(app_name: str = "d365fo-client") -> Path:
+    r"""Get the appropriate user cache directory for the current platform.
+
+    This function follows platform conventions for cache directories:
+    - Windows: %LOCALAPPDATA%\<app_name> (e.g., C:\Users\username\AppData\Local\d365fo-client)
+    - macOS: ~/Library/Caches/<app_name> (e.g., /Users/username/Library/Caches/d365fo-client)
+    - Linux: ~/.cache/<app_name> (e.g., /home/username/.cache/d365fo-client)
+
+    Args:
+        app_name: Name of the application (used as directory name)
+
+    Returns:
+        Path object pointing to the cache directory
+
+    Examples:
+        >>> cache_dir = get_user_cache_dir()
+        >>> print(cache_dir)  # doctest: +SKIP
+        WindowsPath('C:/Users/username/AppData/Local/d365fo-client')
+
+        >>> cache_dir = get_user_cache_dir("my-app")
+        >>> "my-app" in str(cache_dir)
+        True
+    """
+    system = platform.system()
+
+    if system == "Windows":
+        # Use LOCALAPPDATA for cache data on Windows
+        # Falls back to APPDATA if LOCALAPPDATA is not available
+        cache_root = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
+        if cache_root:
+            return Path(cache_root) / app_name
+        else:
+            # Fallback: use user home directory
+            return Path.home() / "AppData" / "Local" / app_name
+
+    elif system == "Darwin":  # macOS
+        # Use ~/Library/Caches on macOS
+        return Path.home() / "Library" / "Caches" / app_name
+
+    else:  # Linux and other Unix-like systems
+        # Use XDG_CACHE_HOME if set, otherwise ~/.cache
+        cache_root = os.environ.get("XDG_CACHE_HOME")
+        if cache_root:
+            return Path(cache_root) / app_name
+        else:
+            return Path.home() / ".cache" / app_name
+
+
+def ensure_directory_exists(path: Union[str, Path]) -> Path:
+    """Ensure a directory exists, creating it if necessary.
+
+    Args:
+        path: Directory path to create
+
+    Returns:
+        Path object pointing to the directory
+
+    Raises:
+        OSError: If directory creation fails
+    """
+    path_obj = Path(path)
+    path_obj.mkdir(parents=True, exist_ok=True)
+    return path_obj
+
+
+def get_default_cache_directory() -> str:
+    r"""Get the default cache directory for d365fo-client.
+
+    This is a convenience function that returns the appropriate cache directory
+    as a string, ready to be used as the default value for metadata_cache_dir.
+
+    Returns:
+        String path to the default cache directory
+
+    Examples:
+        >>> cache_dir = get_default_cache_directory()
+        >>> "d365fo-client" in cache_dir
+        True
+    """
+    return str(get_user_cache_dir())
+
+
+def extract_domain_from_url(url: str) -> str:
+    """Extract and sanitize domain name from URL for use as directory name.
+
+    Args:
+        url: The base URL (e.g., "https://mycompany.sandbox.operations.dynamics.com")
+
+    Returns:
+        Sanitized domain name suitable for directory name
+
+    Examples:
+        >>> extract_domain_from_url("https://mycompany.sandbox.operations.dynamics.com")
+        'mycompany.sandbox.operations.dynamics.com'
+
+        >>> extract_domain_from_url("https://test-env.dynamics.com/")
+        'test-env.dynamics.com'
+
+        >>> extract_domain_from_url("https://localhost:8080")
+        'localhost_8080'
+    """
+    if not url or not url.strip():
+        return "unknown-domain"
+
+    try:
+        parsed = urlparse(url)
+        domain = parsed.netloc.lower()
+
+        # If no netloc (malformed URL), try to extract something useful
+        if not domain:
+            # Try to extract domain-like pattern from the URL
+            domain_match = re.search(r"([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", url)
+            if domain_match:
+                domain = domain_match.group(1).lower()
+            else:
+                # Fallback: create a safe name from the original URL
+                safe_name = re.sub(r"[^\w\.-]", "_", url.lower())
+                return safe_name[:50] or "unknown-domain"
+
+        # Remove default ports for common schemes
+        if (parsed.scheme == "https" and domain.endswith(":443")) or (
+            parsed.scheme == "http" and domain.endswith(":80")
+        ):
+            domain = domain.rsplit(":", 1)[0]
+
+        # Replace invalid filesystem characters with underscore
+        # Windows reserved characters: < > : " | ? * \ /
+        # Also replace other potentially problematic characters
+        domain = re.sub(r'[<>:"|?*\\/]', "_", domain)
+
+        # Replace remaining special characters that might cause issues
+        domain = re.sub(r"[^\w\.-]", "_", domain)
+
+        return domain or "unknown-domain"
+
+    except Exception:
+        # Fallback: create a safe name from the original URL
+        safe_name = re.sub(r"[^\w\.-]", "_", url.lower())
+        return safe_name[:50] or "unknown-domain"  # Limit length
+
+
+def get_environment_cache_dir(base_url: str, app_name: str = "d365fo-client") -> Path:
+    """Get environment-specific cache directory based on F&O base URL.
+
+    This creates a separate cache directory for each F&O environment, allowing
+    users to work with multiple environments without cache conflicts.
+
+    Args:
+        base_url: F&O environment base URL
+        app_name: Application name (default: "d365fo-client")
+
+    Returns:
+        Path object pointing to the environment-specific cache directory
+
+    Examples:
+        >>> cache_dir = get_environment_cache_dir("https://usnconeboxax1aos.cloud.onebox.dynamics.com")
+        >>> "usnconeboxax1aos.cloud.onebox.dynamics.com" in str(cache_dir)
+        True
+
+        >>> cache_dir = get_environment_cache_dir("https://test.dynamics.com", "my-app")
+        >>> "test.dynamics.com" in str(cache_dir) and "my-app" in str(cache_dir)
+        True
+    """
+    domain = extract_domain_from_url(base_url)
+    base_cache_dir = get_user_cache_dir(app_name)
+    return base_cache_dir / domain
+
+
+def get_environment_cache_directory(base_url: str) -> str:
+    """Get environment-specific cache directory as string.
+
+    Convenience function that returns the environment-specific cache directory
+    as a string, ready to be used for metadata_cache_dir.
+
+    Args:
+        base_url: F&O environment base URL
+
+    Returns:
+        String path to the environment-specific cache directory
+
+    Examples:
+        >>> cache_dir = get_environment_cache_directory("https://usnconeboxax1aos.cloud.onebox.dynamics.com")
+        >>> isinstance(cache_dir, str) and "usnconeboxax1aos.cloud.onebox.dynamics.com" in cache_dir
+        True
+    """
+    return str(get_environment_cache_dir(base_url))