pygeobox 1.0.0__py3-none-any.whl

pygeobox/usage.py

@@ -0,0 +1,211 @@
+from urllib.parse import urlencode, urljoin
+from typing import Optional, Dict, List, Union, TYPE_CHECKING
+from datetime import datetime
+
+from .base import Base
+from .user import User
+from .apikey import ApiKey
+from .utils import clean_data
+from .enums import UsageScale, UsageParam
+
+if TYPE_CHECKING:
+    from . import GeoboxClient
+
+
+class Usage(Base):
+
+    BASE_ENDPOINT = 'usage/'
+
+    def __init__(self,
+                api: 'GeoboxClient',
+                user: 'User'):
+        """
+        Constructs the necessary attributes for the Usage object.
+
+        Args:
+            api (Api): The API instance.
+            user (User): the user usage object.
+        """
+        self.api = api
+        self.user = user
+
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the Usage object.
+
+        Returns:
+            str: A string representation of the Usage object.
+        """
+        return f"Usage(user={self.user})"
+
+
+    @classmethod
+    def get_api_usage(cls, 
+                        api: 'GeoboxClient', 
+                        resource: Union['User', 'ApiKey'], 
+                        scale: 'UsageScale',
+                        param: 'UsageParam',
+                        from_date: 'datetime' = None,
+                        to_date: 'datetime' = None,
+                        days_before_now: int = None,
+                        limit: int = None) -> List:
+        """
+        Get the api usage of a user
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            resource (User | ApiKey): User or ApiKey object.
+            scale (UsageScale): the scale of the report.
+            param (UsageParam): traffic or calls.
+            from_date (datetime, optional): datetime object in this format: "%Y-%m-%dT%H:%M:%S". 
+            to_date (datetime, optional): datetime object in this format: "%Y-%m-%dT%H:%M:%S". 
+            days_before_now (int, optional): number of days befor now.
+            limit (int, optional): Number of items to return. default is 10.
+
+        Raises:
+            ValueError: one of days_before_now or from_date/to_date parameters must have value
+            ValueError: resource must be a 'user' or 'apikey' object
+
+        Returns:
+            List: usage report
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.usage import Usage
+            >>> client = GeoboxClient()
+            >>> user = client.get_user() # gets current user
+            >>> usage = Usage.get_api_usage(client, 
+            ...                               resource=user, 
+            ...                               scale=UsageScale.Day, 
+            ...                               param=UsageParam.Calls, 
+            ...                               days_before_now=5)
+            or
+            >>> usage = client.get_api_usage(resource=user, 
+            ...                               scale=UsageScale.Day, 
+            ...                               param=UsageParam.Calls, 
+            ...                               days_before_now=5)
+        """
+        if not(from_date and to_date) and not days_before_now:
+            raise ValueError("one of days_before_now or from_date/to_date parameters must have value")
+
+        params = {}
+        if isinstance(resource, User):
+            params['eid'] = resource.user_id
+        elif isinstance(resource, ApiKey):
+            params['eid'] = resource.key
+        else:
+            raise ValueError("resource must be a 'user' or 'apikey' object")
+
+        params = clean_data({**params,
+                    'scale': scale.value if scale else None,
+                    'param': param.value if param else None,
+                    'from_date': from_date.strftime("%Y-%m-%dT%H:%M:%S.%f") if from_date else None,
+                    'to_date': to_date.strftime("%Y-%m-%dT%H:%M:%S.%f") if to_date else None,
+                    'days_before_now': days_before_now,
+                    'limit': limit
+                    })
+        query_strings = urlencode(params)
+        endpoint = f"{cls.BASE_ENDPOINT}api?{query_strings}"
+
+        return api.get(endpoint)
+
+
+    @classmethod
+    def get_process_usage(cls, 
+                            api: 'GeoboxClient',
+                            user_id: int = None, 
+                            from_date: datetime = None, 
+                            to_date: datetime = None, 
+                            days_before_now: int = None) -> float:
+        """
+        Get process usage of a user in seconds
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            user_id (int, optional): the id of the user. leave blank to get the current user report.
+            from_date (datetime, optional): datetime object in this format: "%Y-%m-%dT%H:%M:%S". 
+            to_date (datetime, optional): datetime object in this format: "%Y-%m-%dT%H:%M:%S". 
+            days_before_now (int, optional): number of days befor now.
+
+        Raises:
+            ValueError: one of days_before_now or from_date/to_date parameters must have value
+
+        Returns:
+            float: process usage of a user in seconds
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.usage import Usage
+            >>> client = GeoboxClient()
+            >>> process_usage = Usage.get_process_usage(client, days_before_now=5)
+            or
+            >>> process_usage = client.get_process_usage(days_before_now=5)
+        """
+        if not(from_date and to_date) and not days_before_now:
+            raise ValueError("one of days_before_now or from_date/to_date parameters must have value")
+
+        params = clean_data({
+            'user_id': user_id if user_id else None,
+            'from_date': from_date.strftime("%Y-%m-%dT%H:%M:%S.%f") if from_date else None,
+            'to_date': to_date.strftime("%Y-%m-%dT%H:%M:%S.%f") if to_date else None,
+            'days_before_now': days_before_now
+        })
+        query_strings = urlencode(params)
+        endpoint = f"{cls.BASE_ENDPOINT}process?{query_strings}"
+        return api.get(endpoint)
+
+
+    @classmethod
+    def get_usage_summary(cls, api: 'GeoboxClient', user_id: int = None) -> Dict:
+        """
+        Get the usage summary of a user
+
+        Args:
+            api (GeoboxClient): The API instance.
+            user_id (int, optional): the id of the user. leave blank to get the current user report.
+
+        Returns:
+            Dict: the usage summery of the users
+
+        Returns:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.usage import Usage
+            >>> client = GeoboxClient()
+            >>> usage_summary = Usage.get_usage_summary(client)
+            or
+            >>> usage_summary = client.get_usage_summary()
+        """
+        params = clean_data({
+            'user_id': user_id if user_id else None
+        })
+        query_strings = urlencode(params)
+        endpoint = f"{cls.BASE_ENDPOINT}summary?{query_strings}"
+        return api.get(endpoint)
+
+
+    @classmethod
+    def update_usage(cls, api: 'GeoboxClient', user_id: int = None) -> Dict:
+        """
+        Update usage of a user
+
+        Args:
+            api (GeoboxClient): The API instance.
+            user_id (int, optional): the id of the user. leave blank to get the current user report.
+            
+        Returns:
+            Dict: the updated data
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.usage import Usage
+            >>> client = GeoboxClient()
+            >>> Usage.update_usage(client)
+            or
+            >>> client.update_usage()
+        """
+        data = clean_data({
+            'user_id': user_id if user_id else None
+        })
+        endpoint = f"{cls.BASE_ENDPOINT}update"
+        return api.post(endpoint, payload=data)

pygeobox/user.py

@@ -0,0 +1,424 @@
+from typing import List, Any, TYPE_CHECKING, Union, Dict
+from urllib.parse import urlencode, urljoin
+
+from .base import Base
+from .utils import clean_data
+from .enums import UserRole, UserStatus
+from .plan import Plan
+
+if TYPE_CHECKING:
+    from . import GeoboxClient
+
+
+class User(Base):
+
+    BASE_ENDPOINT: str = 'users/'
+
+    def __init__(self, api: 'GeoboxClient', user_id: int, data: dict = {}) -> None:
+        """
+        Initialize a User instance.
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            user_id (int): the id of the user
+            data (Dict): The data of the user.
+        """
+        super().__init__(api, data=data)
+        self.user_id = user_id
+        self.endpoint = urljoin(self.BASE_ENDPOINT, f'{self.user_id}/') if self.user_id else 'me'
+
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the User instance.
+
+        Returns:
+            str: A string representation of the User instance.
+        """
+        return f'User(first_name={self.first_name}, last_name={self.last_name})'
+    
+
+    @property
+    def status(self) -> 'UserStatus':
+        """
+        User status Property
+
+        Returns:
+            UserStatus: the user status
+        """
+        return UserStatus(self.data.get('status')) if self.data.get('status') else None
+    
+    
+    @property
+    def plan(self) -> 'Plan':
+        """
+        User plan Property
+
+        Returns:
+            Plan: the plan object
+        """
+        plan = self.data.get('plan', {})
+        return Plan(self.api, plan.get('id'), plan) if plan else None
+    
+
+    @classmethod
+    def get_users(cls, api: 'GeoboxClient', **kwargs) -> Union[List['User'], int]:
+        """
+        Retrieves a list of users (Permission Required)
+
+        Args:
+            api (GeoboxClient): The API instance.
+
+        Keyword Args:
+            status (UserStatus): the status of the users filter.
+            q (str): query filter based on OGC CQL standard. e.g. "field1 LIKE '%GIS%' AND created_at > '2021-01-01'"
+            search (str): search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.
+            search_fields (str): comma separated list of fields for searching.
+            order_by (str): comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: "A" denotes ascending order and "D" denotes descending order.
+            return_count (bool): Whether to return total count. default is False.
+            skip (int): Number of items to skip. default is 0.
+            limit (int): Number of items to return. default is 10.
+            user_id (int): Specific user. privileges required.
+            shared (bool): Whether to return shared maps. default is False.
+
+        Returns:
+            List[User] | int: list of users or the count number.
+
+        Example:
+            >>> from geobox import Geoboxclient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> users = User.get_users(client)
+            or
+            >>> users = client.get_users()
+        """
+        params = {
+           'f': 'json',
+           'q': kwargs.get('q'),
+           'search': kwargs.get('search'),
+           'search_fields': kwargs.get('search_fields'),
+           'order_by': kwargs.get('order_by'),
+           'return_count': kwargs.get('return_count', False),
+           'skip': kwargs.get('skip', 0),
+           'limit': kwargs.get('limit', 10),
+           'user_id': kwargs.get('user_id'),
+           'shared': kwargs.get('shared', False)
+        }
+        return super()._get_list(api, cls.BASE_ENDPOINT, params, factory_func=lambda api, item: User(api, item['id'], item))
+
+    
+
+    @classmethod
+    def create_user(cls, 
+                    api: 'GeoboxClient',
+                    username: str, 
+                    email: str, 
+                    password: str, 
+                    role: 'UserRole',
+                    first_name: str,
+                    last_name: str,
+                    mobile: str,
+                    status: 'UserStatus') -> 'User':
+        """
+        Create a User (Permission Required)
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            username (str): the username of the user.
+            email (str): the email of the user.
+            password (str): the password of the user.
+            role (UserRole): the role of the user.
+            first_name (str): the firstname of the user.
+            last_name (str): the lastname of the user.
+            mobile (str): the mobile number of the user. e.g. "+98 9120123456".
+            status (UserStatus): the status of the user.
+
+        Returns:
+            User: the user object.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = User.create_user(client,
+            ...                             username="user1",
+            ...                             email="user1@example.com",
+            ...                             password="P@ssw0rd",
+            ...                             role=UserRole.ACCOUNT_ADMIN,
+            ...                             first_name="user 1",
+            ...                             last_name="user 1",
+            ...                             mobile="+98 9120123456",
+            ...                             status=UserStatus.ACTIVE)
+            or
+            >>> user = client.create_user(username="user1",
+            ...                             email="user1@example.com",
+            ...                             password="P@ssw0rd",
+            ...                             role=UserRole.ACCOUNT_ADMIN,
+            ...                             first_name="user 1",
+            ...                             last_name="user 1",
+            ...                             mobile="+98 9120123456",
+            ...                             status=UserStatus.ACTIVE)
+        """
+        data = {
+            "username": username,
+            "email": email,
+            "password": password,
+            "role": role.value,
+            "first_name": first_name,
+            "last_name": last_name,
+            "mobile": mobile,
+            "status": status.value
+        }
+        return super()._create(api, cls.BASE_ENDPOINT, data, factory_func=lambda api, item: User(api, item['id'], item))
+
+
+
+    @classmethod
+    def search_users(cls, api: 'GeoboxClient', search: str = None, skip: int = 0, limit: int = 10) -> List['User']:
+        """
+        Get list of users based on the search term.
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            search (str, optional): The Search Term.
+            skip (int, optional): Number of items to skip. default is 0.
+            limit (int, optional): Number of items to return. default is 10.
+
+        Returns:
+            List[User]: A list of User instances.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> users = User.get_users(client, search="John")
+            or
+            >>> users = client.get_users(search="John")
+        """
+        params = {
+            'search': search,
+            'skip': skip,
+            'limit': limit
+        }
+        endpoint = urljoin(cls.BASE_ENDPOINT, 'search/')
+        return super()._get_list(api, endpoint, params, factory_func=lambda api, item: User(api, item['id'], item))
+
+
+    @classmethod
+    def get_user(cls, api: 'GeoboxClient', user_id: int = 'me') -> 'User':
+        """
+        Get a user by its id (Permission Required)
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            user_id (int, optional): Specific user. don't specify a user_id to get the current user.
+
+        Returns:
+            User: the user object.
+
+        Raises:
+            NotFoundError: If the user with the specified id is not found.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = User.get_user(client, user_id=1)
+            or
+            >>> user = client.get_user(user_id=1)
+        
+            get the current user
+            >>> user = User.get_user(client)
+            or 
+            >>> user = client.get_user()
+        """
+        params = {
+            'f': 'json'
+        }
+        return super()._get_detail(api, cls.BASE_ENDPOINT, user_id, params, factory_func=lambda api, item: User(api, item['id'], item))
+
+
+    def update(self, **kwargs) -> Dict:
+        """
+        Update the user (Permission Required)
+
+        Keyword Args:
+            username (str)
+            email (str)
+            first_name (str)
+            last_name (str)
+            mobile (str): e.g. "+98 9120123456" 
+            status (UserStatus)
+            role (UserRole)
+            plan (Plan)
+            expiration_date (str)
+
+        Returns:
+            Dict: updated data
+
+        Example:
+            >>> from geobox imoprt GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = User.get_user(client, user_id=1)
+            >>> user.update_user(status=UserStatus.PENDING)
+        """
+        data = {
+            "csrf_token": kwargs.get('csrf_token'),
+            "username": kwargs.get('username'),
+            "email": kwargs.get('email'),
+            "first_name": kwargs.get('first_name'),
+            "last_name": kwargs.get('last_name'),
+            "mobile": kwargs.get('mobile'),
+            "status": kwargs.get('status').value if kwargs.get('status') else None,
+            "role": kwargs.get('role').value if kwargs.get('role') else None,
+            "plan_id": kwargs.get('plan').id if kwargs.get('plan') else None,
+            "expiration_date": kwargs.get('expiration_date')
+        }
+        return super()._update(self.endpoint, data)
+    
+
+    def delete(self) -> None:
+        """
+        Delete the user (Permission Required)
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = User.get_user(client, user_id=1)
+            >>> user.delete()
+        """
+        super().delete(self.endpoint)
+
+    
+    def get_sessions(self, user_id: int = 'me') -> List['Session']:
+        """
+        Get a list of user available sessions (Permission Required)
+
+        Args:
+            user_id (int, optional): Specific user. don't specify user_id to get the current user.
+
+        Returns:
+            List[Session]: list of user sessions.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = User.get_user(client, user_id=1)
+            or
+            >>> user = client.get_user(user_id=1)
+
+            >>> user.get_user_sessions()       
+            or
+            >>> client.get_user_sessions()
+        """
+        params = clean_data({
+            'f': 'json'
+        })
+        query_string = urlencode(params)
+        if user_id != 'me':
+            user = self.get_user(self.api, user_id=user_id)
+            endpoint = f"{self.BASE_ENDPOINT}{user_id}/sessions/?{query_string}"
+        else:
+            user = self
+            endpoint = urljoin(self.endpoint, f'sessions/?{query_string}')
+
+        response = self.api.get(endpoint)
+        return [Session(item['uuid'], item, user) for item in response]
+    
+
+    def change_password(self, new_password: str) -> None:
+        """
+        Change the user password (privileges required)
+
+        Args:
+            new_password (str): new password for the user.
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = client.get_user()
+            >>> user.change_password(new_password='user_new_password')
+        """
+        data = clean_data({
+            "new_password": new_password
+        })
+        endpoint = urljoin(self.endpoint, 'change-password')
+        self.api.post(endpoint, data, is_json=False)
+
+
+    def renew_plan(self) -> None:
+        """
+        Renew the user plan
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> user = client.get_user(user_id=1)
+            >>> user.renew_plan()
+        """
+        endpoint = urljoin(self.endpoint, 'renewPlan')
+        self.api.post(endpoint)
+
+
+
+
+class Session(Base):
+    def __init__(self, uuid: str, data: Dict, user: 'User'):
+        """
+        Initialize a user session instance.
+
+        Args:
+            uuid (str): The unique identifier for the user session.
+            data (Dict): The data of the session.
+            user (User): the user instance.
+        """
+        self.uuid = uuid
+        self.data = data
+        self.user = user
+        self.endpoint = urljoin(self.user.endpoint, f'sessions/{self.uuid}')
+
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the resource.
+
+        Returns:
+            str: A string representation of the Session object.
+        """
+        return f"Session(user={self.user}, agent='{self.agent}')"
+    
+
+    def close(self) -> None:
+        """
+        Close the user session
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import geoboxClient
+            >>> from geobox.user import User
+            >>> client = GeoboxClient()
+            >>> user = User.get_user(client) # without user_id parameter, it gets the current user
+            or
+            >>> user = client.get_user() # without user_id parameter, it gets the current user
+            >>> session = user.get_sessions()[0]
+            >>> session.close()
+        """
+        data = clean_data({
+            'user_id': self.user.user_id,
+            'session_uuid': self.uuid
+        })
+        self.user.api.post(self.endpoint, data)

pygeobox/utils.py

@@ -0,0 +1,44 @@
+from urllib.parse import urlparse, parse_qs, urlencode, urlunparse
+
+
+def clean_data(data: dict) -> dict:
+    """
+    Cleans the input data by removing keys with None values.
+
+    Args:
+        data (dict): The input data.
+
+    Returns:
+        dict: The cleaned data.
+    """
+    return {k: v for k, v in data.items() if v is not None}
+
+def join_url_params(base_url: str, params: dict) -> str:
+    """
+    Join URL with parameters while preserving existing query parameters.
+    
+    Args:
+        base_url (str): Base URL that may contain existing parameters
+        params (dict): New parameters to add
+        
+    Returns:
+        str: URL with all parameters properly joined
+    """
+    # Parse the URL
+    parsed = urlparse(base_url)
+    
+    # Get existing parameters
+    existing_params = parse_qs(parsed.query)
+    
+    # Update with new parameters
+    existing_params.update(params)
+    
+    # Reconstruct the URL
+    return urlunparse((
+        parsed.scheme,
+        parsed.netloc,
+        parsed.path,
+        parsed.params,
+        urlencode(existing_params, doseq=True),
+        parsed.fragment
+    ))