adss 1.0__py3-none-any.whl → 1.2__py3-none-any.whl

adss/endpoints/users.py

@@ -0,0 +1,311 @@
+"""
+User management functionality for the Astronomy TAP Client.
+"""
+import requests
+from typing import Dict, List, Optional, Any
+
+from adss.exceptions import (
+    AuthenticationError, ResourceNotFoundError, PermissionDeniedError,
+    ValidationError
+)
+from adss.utils import handle_response_errors
+from adss.models.user import User, Role
+
+
+class UsersEndpoint:
+    """
+    Handles user management operations.
+    """
+    
+    def __init__(self, base_url: str, auth_manager):
+        """
+        Initialize the Users endpoint.
+        
+        Args:
+            base_url: The base URL of the API server
+            auth_manager: Authentication manager providing auth headers
+        """
+        self.base_url = base_url.rstrip('/')
+        self.auth_manager = auth_manager
+    
+    def register(self, username: str, email: str, password: str, full_name: Optional[str] = None, **kwargs) -> User:
+        """
+        Register a new user account.
+        
+        Args:
+            username: Desired username
+            email: User's email address
+            password: User's password (will be validated for strength)
+            full_name: Optional full name
+            **kwargs: Additional keyword arguments to pass to the request (e.g., verify=False)
+            
+        Returns:
+            The newly created User object
+            
+        Raises:
+            ValidationError: If input validation fails (e.g., password too weak)
+        """
+        data = {
+            "username": username,
+            "email": email,
+            "password": password
+        }
+        
+        if full_name:
+            data["full_name"] = full_name
+        
+        try:
+            response = self.auth_manager.request(
+                method="POST",
+                url="/adss/v1/users",
+                json=data,
+                **kwargs
+            )
+            handle_response_errors(response)
+            
+            user_data = response.json()
+            return User.from_dict(user_data)
+            
+        except Exception as e:
+            if hasattr(e, 'response') and e.response.status_code == 400:
+                try:
+                    error_data = e.response.json()
+                    raise ValidationError(
+                        f"User registration failed: {error_data.get('detail', str(e))}",
+                        error_data.get('errors')
+                    )
+                except (ValueError, AttributeError):
+                    pass
+            raise
+    
+    def get_me(self, **kwargs) -> User:
+        """
+        Get information about the currently authenticated user.
+        
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request (e.g., verify=False)
+            
+        Returns:
+            The current User object
+            
+        Raises:
+            AuthenticationError: If not authenticated
+        """
+        try:
+            response = self.auth_manager.request(
+                method="GET",
+                url="/adss/v1/users/me",
+                auth_required=True,
+                **kwargs
+            )
+            handle_response_errors(response)
+            
+            user_data = response.json()
+            return User.from_dict(user_data)
+            
+        except Exception as e:
+            if hasattr(e, 'response') and e.response.status_code == 401:
+                raise AuthenticationError("Authentication required")
+            raise
+    
+    def update_profile(self, 
+                     email: Optional[str] = None, 
+                     full_name: Optional[str] = None,
+                     **kwargs) -> User:
+        """
+        Update the current user's profile information.
+        
+        Args:
+            email: New email address (optional)
+            full_name: New full name (optional)
+            **kwargs: Additional keyword arguments to pass to the request (e.g., verify=False)
+            
+        Returns:
+            The updated User object
+            
+        Raises:
+            AuthenticationError: If not authenticated
+            ValidationError: If input validation fails
+        """
+        data = {}
+        if email is not None:
+            data["email"] = email
+        if full_name is not None:
+            data["full_name"] = full_name
+        
+        if not data:
+            # Nothing to update
+            return self.get_me(**kwargs)
+        
+        try:
+            response = self.auth_manager.request(
+                method="PATCH",
+                url="/adss/v1/users/me",
+                json=data,
+                auth_required=True,
+                **kwargs
+            )
+            handle_response_errors(response)
+            
+            user_data = response.json()
+            return User.from_dict(user_data)
+            
+        except Exception as e:
+            if hasattr(e, 'response') and e.response.status_code == 400:
+                try:
+                    error_data = e.response.json()
+                    raise ValidationError(
+                        f"Profile update failed: {error_data.get('detail', str(e))}",
+                        error_data.get('errors')
+                    )
+                except (ValueError, AttributeError):
+                    pass
+            elif hasattr(e, 'response') and e.response.status_code == 401:
+                raise AuthenticationError("Authentication required")
+            raise
+    
+    def get_users(self, skip: int = 0, limit: int = 100, **kwargs) -> List[User]:
+        """
+        Get a list of users (staff only).
+        
+        Args:
+            skip: Number of users to skip (for pagination)
+            limit: Maximum number of users to return
+            **kwargs: Additional keyword arguments to pass to the request (e.g., verify=False)
+            
+        Returns:
+            List of User objects
+            
+        Raises:
+            AuthenticationError: If not authenticated
+            PermissionDeniedError: If not a staff user
+        """
+        params = {"skip": skip, "limit": limit}
+        
+        try:
+            response = self.auth_manager.request(
+                method="GET",
+                url="/adss/v1/users",
+                params=params,
+                auth_required=True,
+                **kwargs
+            )
+            handle_response_errors(response)
+            
+            users_data = response.json()
+            return [User.from_dict(user_data) for user_data in users_data]
+            
+        except Exception as e:
+            if hasattr(e, 'response'):
+                if e.response.status_code == 401:
+                    raise AuthenticationError("Authentication required")
+                elif e.response.status_code == 403:
+                    raise PermissionDeniedError("Staff access required")
+            raise
+    
+    def get_user(self, user_id: str, **kwargs) -> User:
+        """
+        Get information about a specific user (staff only).
+        
+        Args:
+            user_id: ID of the user to get
+            **kwargs: Additional keyword arguments to pass to the request (e.g., verify=False)
+            
+        Returns:
+            User object
+            
+        Raises:
+            AuthenticationError: If not authenticated
+            PermissionDeniedError: If not a staff user
+            ResourceNotFoundError: If the user is not found
+        """
+        try:
+            response = self.auth_manager.request(
+                method="GET",
+                url=f"/adss/v1/users/{user_id}",
+                auth_required=True,
+                **kwargs
+            )
+            handle_response_errors(response)
+            
+            user_data = response.json()
+            return User.from_dict(user_data)
+            
+        except Exception as e:
+            if hasattr(e, 'response'):
+                if e.response.status_code == 401:
+                    raise AuthenticationError("Authentication required")
+                elif e.response.status_code == 403:
+                    raise PermissionDeniedError("Staff access required")
+                elif e.response.status_code == 404:
+                    raise ResourceNotFoundError(f"User not found: {user_id}")
+            raise
+    
+    def update_user(self, 
+                   user_id: str, 
+                   email: Optional[str] = None, 
+                   full_name: Optional[str] = None, 
+                   is_active: Optional[bool] = None,
+                   **kwargs) -> User:
+        """
+        Update a user's information (staff only).
+        
+        Args:
+            user_id: ID of the user to update
+            email: New email address (optional)
+            full_name: New full name (optional)
+            is_active: New active status (optional)
+            **kwargs: Additional keyword arguments to pass to the request (e.g., verify=False)
+            
+        Returns:
+            The updated User object
+            
+        Raises:
+            AuthenticationError: If not authenticated
+            PermissionDeniedError: If not a staff user
+            ResourceNotFoundError: If the user is not found
+            ValidationError: If input validation fails
+        """
+        data = {}
+        if email is not None:
+            data["email"] = email
+        if full_name is not None:
+            data["full_name"] = full_name
+        if is_active is not None:
+            data["is_active"] = is_active
+        
+        if not data:
+            # Nothing to update
+            return self.get_user(user_id, **kwargs)
+        
+        try:
+            response = self.auth_manager.request(
+                method="PATCH",
+                url=f"/adss/v1/users/{user_id}",
+                json=data,
+                auth_required=True,
+                **kwargs
+            )
+            handle_response_errors(response)
+            
+            user_data = response.json()
+            return User.from_dict(user_data)
+            
+        except Exception as e:
+            if hasattr(e, 'response'):
+                if e.response.status_code == 401:
+                    raise AuthenticationError("Authentication required")
+                elif e.response.status_code == 403:
+                    raise PermissionDeniedError("Staff access required")
+                elif e.response.status_code == 404:
+                    raise ResourceNotFoundError(f"User not found: {user_id}")
+                elif e.response.status_code == 400:
+                    try:
+                        error_data = e.response.json()
+                        raise ValidationError(
+                            f"User update failed: {error_data.get('detail', str(e))}",
+                            error_data.get('errors')
+                        )
+                    except (ValueError, AttributeError):
+                        pass
+            raise

adss/exceptions.py

@@ -0,0 +1,57 @@
+"""
+Custom exceptions for the Astronomy TAP Client.
+"""
+
+class ADSSClientError(Exception):
+    """Base exception for all TAP client errors."""
+    
+    def __init__(self, message, response=None):
+        self.message = message
+        self.response = response
+        super().__init__(self.message)
+
+
+class AuthenticationError(ADSSClientError):
+    """Exception raised for authentication failures."""
+    pass
+
+
+class PermissionDeniedError(ADSSClientError):
+    """Exception raised when the user doesn't have sufficient permissions."""
+    pass
+
+
+class ResourceNotFoundError(ADSSClientError):
+    """Exception raised when a requested resource is not found."""
+    pass
+
+
+class QueryExecutionError(ADSSClientError):
+    """Exception raised when a query fails to execute."""
+    
+    def __init__(self, message, query=None, response=None):
+        self.query = query
+        super().__init__(message, response)
+
+
+class ValidationError(ADSSClientError):
+    """Exception raised when input validation fails."""
+    
+    def __init__(self, message, errors=None, response=None):
+        self.errors = errors or {}
+        super().__init__(message, response)
+
+
+class ConnectionError(ADSSClientError):
+    """Exception raised when connection to the API server fails."""
+    pass
+
+
+class TimeoutError(ADSSClientError):
+    """Exception raised when a request times out."""
+    pass
+
+
+class ServerError(ADSSClientError):
+    """Exception raised when the server returns a 5xx error."""
+    pass

adss/models/__init__.py

@@ -0,0 +1,13 @@
+"""
+Data models for the Astronomy TAP Client.
+"""
+
+from .user import User, Role, SchemaPermission, TablePermission, RolePermissions
+from .query import Query, QueryResult
+from .metadata import Column, Table, Schema, DatabaseMetadata
+
+__all__ = [
+    'User', 'Role', 'SchemaPermission', 'TablePermission', 'RolePermissions',
+    'Query', 'QueryResult',
+    'Column', 'Table', 'Schema', 'DatabaseMetadata'
+]

adss/models/metadata.py

@@ -0,0 +1,138 @@
+"""
+Database metadata models for the Astronomy TAP Client.
+"""
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+
+@dataclass
+class Column:
+    """
+    Represents a database column and its metadata.
+    """
+    name: str
+    data_type: str
+    is_nullable: bool
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Column':
+        """Create a Column object from a dictionary."""
+        return cls(
+            name=data.get('name'),
+            data_type=data.get('data_type'),
+            is_nullable=data.get('is_nullable', False)
+        )
+
+
+@dataclass
+class Table:
+    """
+    Represents a database table and its columns.
+    """
+    name: str
+    columns: List[Column] = field(default_factory=list)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Table':
+        """Create a Table object from a dictionary."""
+        columns = [
+            Column.from_dict(col_data) 
+            for col_data in data.get('columns', [])
+        ]
+        
+        return cls(
+            name=data.get('name'),
+            columns=columns
+        )
+    
+    def get_column(self, name: str) -> Optional[Column]:
+        """Get a column by name."""
+        for column in self.columns:
+            if column.name == name:
+                return column
+        return None
+    
+    def has_column(self, name: str) -> bool:
+        """Check if the table has a column with the given name."""
+        return any(col.name == name for col in self.columns)
+    
+    def column_names(self) -> List[str]:
+        """Get a list of all column names."""
+        return [col.name for col in self.columns]
+
+
+@dataclass
+class Schema:
+    """
+    Represents a database schema and its tables.
+    """
+    name: str
+    tables: List[Table] = field(default_factory=list)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Schema':
+        """Create a Schema object from a dictionary."""
+        tables = [
+            Table.from_dict(table_data) 
+            for table_data in data.get('tables', [])
+        ]
+        
+        return cls(
+            name=data.get('name'),
+            tables=tables
+        )
+    
+    def get_table(self, name: str) -> Optional[Table]:
+        """Get a table by name."""
+        for table in self.tables:
+            if table.name == name:
+                return table
+        return None
+    
+    def has_table(self, name: str) -> bool:
+        """Check if the schema has a table with the given name."""
+        return any(table.name == name for table in self.tables)
+    
+    def table_names(self) -> List[str]:
+        """Get a list of all table names in the schema."""
+        return [table.name for table in self.tables]
+
+
+@dataclass
+class DatabaseMetadata:
+    """
+    Represents database metadata, including schemas and their tables.
+    """
+    schemas: List[Schema] = field(default_factory=list)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'DatabaseMetadata':
+        """Create a DatabaseMetadata object from a dictionary."""
+        schemas = [
+            Schema.from_dict(schema_data) 
+            for schema_data in data.get('schemas', [])
+        ]
+        
+        return cls(schemas=schemas)
+    
+    def get_schema(self, name: str) -> Optional[Schema]:
+        """Get a schema by name."""
+        for schema in self.schemas:
+            if schema.name == name:
+                return schema
+        return None
+    
+    def has_schema(self, name: str) -> bool:
+        """Check if the database has a schema with the given name."""
+        return any(schema.name == name for schema in self.schemas)
+    
+    def schema_names(self) -> List[str]:
+        """Get a list of all schema names."""
+        return [schema.name for schema in self.schemas]
+    
+    def get_table(self, schema_name: str, table_name: str) -> Optional[Table]:
+        """Get a table by schema and table name."""
+        schema = self.get_schema(schema_name)
+        if schema:
+            return schema.get_table(table_name)
+        return None

adss/models/query.py

@@ -0,0 +1,134 @@
+"""
+Query-related data models for the Astronomy TAP Client.
+"""
+from dataclasses import dataclass
+from typing import Dict, Optional, Any, List
+from datetime import datetime
+import pandas as pd
+
+from adss.utils import parse_datetime
+
+
+@dataclass
+class Query:
+    """
+    Represents a database query and its metadata.
+    """
+    id: str
+    query_text: str
+    status: str  # 'PENDING', 'QUEUED', 'RUNNING', 'COMPLETED', 'ERROR'
+    created_at: datetime
+    mode: str = 'adql'  # 'adql' or 'sql'
+    user_id: Optional[str] = None
+    completed_at: Optional[datetime] = None
+    result_url: Optional[str] = None
+    error: Optional[str] = None
+    execution_time_ms: Optional[int] = None
+    row_count: Optional[int] = None
+    position_in_queue: Optional[int] = None
+    expires_at: Optional[datetime] = None
+    query_metadata: Optional[Dict[str, Any]] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Query':
+        """Create a Query object from a dictionary."""
+        query_id = data.get('id')
+        query_text = data.get('query_text')
+        status = data.get('status')
+        mode = data.get('mode', 'adql')
+        user_id = data.get('user_id')
+        
+        created_at = parse_datetime(data.get('created_at'))
+        completed_at = parse_datetime(data.get('completed_at'))
+        expires_at = parse_datetime(data.get('expires_at'))
+        
+        result_url = data.get('result_url')
+        error = data.get('error')
+        execution_time_ms = data.get('execution_time_ms')
+        row_count = data.get('row_count')
+        position_in_queue = data.get('position_in_queue')
+        query_metadata = data.get('query_metadata')
+        
+        return cls(
+            id=query_id,
+            query_text=query_text,
+            status=status,
+            mode=mode,
+            user_id=user_id,
+            created_at=created_at,
+            completed_at=completed_at,
+            result_url=result_url,
+            error=error,
+            execution_time_ms=execution_time_ms,
+            row_count=row_count,
+            position_in_queue=position_in_queue,
+            expires_at=expires_at,
+            query_metadata=query_metadata
+        )
+    
+    @property
+    def is_complete(self) -> bool:
+        """Check if the query has completed (successfully or with error)."""
+        return self.status in ['COMPLETED', 'ERROR']
+    
+    @property
+    def is_running(self) -> bool:
+        """Check if the query is currently running."""
+        return self.status == 'RUNNING'
+    
+    @property
+    def is_queued(self) -> bool:
+        """Check if the query is queued."""
+        return self.status == 'QUEUED'
+    
+    @property
+    def is_successful(self) -> bool:
+        """Check if the query completed successfully."""
+        return self.status == 'COMPLETED'
+    
+    @property
+    def is_failed(self) -> bool:
+        """Check if the query failed."""
+        return self.status == 'ERROR'
+
+
+@dataclass
+class QueryResult:
+    """
+    Represents the result of a query, including the data and metadata.
+    """
+    query: Query
+    data: pd.DataFrame
+    execution_time_ms: Optional[int] = None
+    row_count: Optional[int] = None
+    column_count: Optional[int] = None
+    
+    def to_csv(self, path: str, **kwargs) -> None:
+        """Save the query result to a CSV file."""
+        self.data.to_csv(path, **kwargs)
+    
+    def to_parquet(self, path: str, **kwargs) -> None:
+        """Save the query result to a Parquet file."""
+        self.data.to_parquet(path, **kwargs)
+    
+    def to_json(self, path: str = None, **kwargs) -> Optional[str]:
+        """
+        Convert the query result to JSON.
+        If path is provided, saves to file, otherwise returns a JSON string.
+        """
+        if path:
+            self.data.to_json(path, **kwargs)
+            return None
+        return self.data.to_json(**kwargs)
+    
+    def head(self, n: int = 5) -> pd.DataFrame:
+        """Return the first n rows of the result."""
+        return self.data.head(n)
+    
+    def tail(self, n: int = 5) -> pd.DataFrame:
+        """Return the last n rows of the result."""
+        return self.data.tail(n)
+    
+    def describe(self) -> pd.DataFrame:
+        """Return summary statistics of the result."""
+        return self.data.describe()