geobox 1.3.3__tar.gz → 1.4.0__tar.gz

{geobox-1.3.3 → geobox-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geobox
-Version: 1.3.3
+Version: 1.4.0
 Summary: SDK for Geobox's APIs
 Author-email: Hamid Heydari <heydari.h62@gmail.com>
 License: MIT
@@ -31,6 +31,8 @@ Geobox® is a cloud-based GIS platform that enables users (local governments, co
 
 Geobox python SDK provides seamless integration with the Geobox API, enabling developers to work with geospatial data and services programmatically. This comprehensive toolkit empowers applications to leverage advanced geospatial capabilities including data management and analysis.
 
+[Here](https://geobox.readthedocs.io) you can find the official documentation for Geobox Python SDK.
+
 Installation
 ============
 

{geobox-1.3.3 → geobox-1.4.0}/README.md

@@ -5,6 +5,8 @@ Geobox® is a cloud-based GIS platform that enables users (local governments, co
 
 Geobox python SDK provides seamless integration with the Geobox API, enabling developers to work with geospatial data and services programmatically. This comprehensive toolkit empowers applications to leverage advanced geospatial capabilities including data management and analysis.
 
+[Here](https://geobox.readthedocs.io) you can find the official documentation for Geobox Python SDK.
+
 Installation
 ============
 

{geobox-1.3.3 → geobox-1.4.0}/geobox/api.py

@@ -20,6 +20,7 @@ from .map import Map
 from .user import User, UserRole, UserStatus, Session
 from .query import Query
 from .workflow import Workflow
+from .layout import Layout
 from .version import VectorLayerVersion
 from .tile3d import Tile3d
 from .settings import SystemSettings
@@ -1535,7 +1536,7 @@ class GeoboxClient:
         Example:
             >>> from geobox import GeoboxClient
             >>> client = GeoboxClient()
-            >>> workflows = client.get_workflow(q="name LIKE '%My workflow%'")
+            >>> workflows = client.get_workflows(q="name LIKE '%My workflow%'")
         """
         return Workflow.get_workflows(self, **kwargs)
     
@@ -1681,6 +1682,105 @@ class GeoboxClient:
         return VectorLayerVersion.get_version_by_name(self, name, user_id)
     
 
+    def get_layouts(self, **kwargs) -> Union[List['Layout'], int]:
+        """
+        Get list of layouts with optional filtering and pagination.
+
+        Keyword Args:
+            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 layouts. default is False.
+
+        Returns:
+            List[Layout] | int: A list of layout instances or the total number of layouts.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> layouts = client.get_layouts(q="name LIKE '%My layout%'")
+        """
+        return Layout.get_layouts(self, **kwargs)
+    
+
+    def create_layout(self,
+                    name: str, 
+                    display_name: str = None, 
+                    description: str = None, 
+                    settings: Dict = {}, 
+                    thumbnail: str = None, 
+                    user_id: int = None) -> 'Layout':
+        """
+        Create a new layout.
+
+        Args:
+            name (str): The name of the layout.
+            display_name (str): The display name of the layout.
+            description (str): The description of the layout.
+            settings (Dict): The settings of the layout.
+            thumbnail (str): The thumbnail of the layout.
+            user_id (int): Specific user. privileges layout.
+
+        Returns:
+            Layout: The newly created layout instance.
+
+        Raises:
+            ValidationError: If the layout data is invalid.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> layout = client.create_layout(name="my_layout")
+        """
+        return Layout.create_layout(self, name, display_name, description, settings, thumbnail, user_id)
+
+
+    def get_layout(self, uuid: str, user_id: int = None) -> 'Layout':
+        """
+        Get a layout by its UUID.
+
+        Args:
+            uuid (str): The UUID of the layout to get.
+            user_id (int): Specific user. privileges required.
+
+        Returns:
+            Layout: The layout object.
+
+        Raises:
+            NotFoundError: If the layout with the specified UUID is not found.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> layout = client.get_layout(uuid="12345678-1234-5678-1234-567812345678")
+        """
+        return Layout.get_layout(self, uuid, user_id)
+
+
+    def get_layout_by_name(self, name: str, user_id: int = None) -> Union['Layout', None]:
+        """
+        Get a layout by name
+
+        Args:
+            name (str): the name of the layout to get
+            user_id (int, optional): specific user. privileges required.
+
+        Returns:
+            Layout | None: returns the layout if a layout matches the given name, else None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> layout = client.get_layout_by_name(name='test')
+        """
+        return Layout.get_layout_by_name(self, name, user_id)
+
+
     def get_3dtiles(self, **kwargs) -> Union[List['Tile3d'], int]:
         """
         Get list of 3D Tiles with optional filtering and pagination.
@@ -2016,6 +2116,25 @@ class GeoboxClient:
         return Plan.get_plan(self, plan_id)
     
 
+    def get_plan_by_name(self, name: str) -> Union['Plan', None]:
+        """
+        Get a plan by name
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            name (str): the name of the plan to get
+
+        Returns:
+            Plan | None: returns the plan if a plan matches the given name, else None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> plan = client.get_plan_by_name(name='test')
+        """
+        return Plan.get_plan_by_name(self, name)
+    
+
     def get_dashboards(self, **kwargs) -> Union[List['Dashboard'], int]:
         """
         Get list of Dashboards

{geobox-1.3.3 → geobox-1.4.0}/geobox/apikey.py

@@ -176,11 +176,14 @@ class ApiKey(Base):
             >>> apikey = ApiKey.get_apikey(client, key_id=1)
             >>> apikey.update(name="updated_name")
         """
-        data = {
+        data = clean_data({
             "name": name,
             "user_id": user_id
-        }
-        return super()._update(self.endpoint, data)
+        })
+
+        response = self.api.put(self.endpoint, data, is_json=False)
+        self._update_properties(response)
+        return response
 
 
     def delete(self) -> None:

{geobox-1.3.3 → geobox-1.4.0}/geobox/attachment.py

@@ -31,7 +31,7 @@ class Attachment(Base):
         """
         super().__init__(api, data=data)
         self.attachment_id = attachment_id
-        self.endpoint = urljoin(self.BASE_ENDPOINT, str(self.attachment_id))
+        self.endpoint = f"{self.BASE_ENDPOINT}{str(self.attachment_id)}/"
 
 
     def __repr__(self) -> str:
@@ -293,6 +293,5 @@ class Attachment(Base):
             >>> attachment.thumbnail
             'https://example.com/thumbnail.png'
         """
-        endpoint = f"{self.api.base_url}{self.endpoint}thumbnail"
-        return endpoint
+        return super().thumbnail(format='')
     

{geobox-1.3.3 → geobox-1.4.0}/geobox/base.py

@@ -362,3 +362,24 @@ class Base:
         
         # If all parsing fails, return the original string
         return date_string
+
+
+    def thumbnail(self, format='.png') -> str:
+        """
+        Get the thumbnail URL of the resource.
+        
+        Returns:
+            str: The thumbnail URL
+
+        Raises:
+            ValueError: 
+        """
+        endpoint = f'{self.api.base_url}{self.endpoint}thumbnail{format}'
+        
+        if not self.api.access_token and self.api.apikey:
+            endpoint = f'{endpoint}?apikey={self.api.apikey}'
+            
+        elif not self.api.access_token and not self.api.apikey:
+            raise ValueError("either access_token or apikey must be available for this action.")
+        
+        return endpoint

{geobox-1.3.3 → geobox-1.4.0}/geobox/basemap.py

@@ -23,7 +23,7 @@ class Basemap(Base):
             data (Dict): The data of the basemap.
         """
         super().__init__(api, data=data)
-        self.endpoint = f"{self.BASE_ENDPOINT}{self.data.get('name')}"
+        self.endpoint = f"{self.BASE_ENDPOINT}{self.data.get('name')}/"
 
 
     @classmethod
@@ -107,7 +107,11 @@ class Basemap(Base):
         Returns:
             str: the wmts url
         """
-        endpoint = f"{self.api.base_url}{self.endpoint}/wmts" 
+        endpoint = urljoin(self.api.base_url, f'{self.endpoint}wmts/')
+
+        if not self.api.access_token and self.api.apikey:
+            endpoint = f"{endpoint}?apikey={self.api.apikey}"
+            
         return endpoint
     
 

{geobox-1.3.3 → geobox-1.4.0}/geobox/dashboard.py

@@ -243,8 +243,7 @@ class Dashboard(Base):
             >>> dashboard.thumbnail
             'https://example.com/thumbnail.png'
         """
-        endpoint = urljoin(self.api.base_url, f'{self.endpoint}thumbnail.png')
-        return endpoint
+        return super().thumbnail()
     
 
     def share(self, users: List['User']) -> None:

{geobox-1.3.3 → geobox-1.4.0}/geobox/enums.py

@@ -19,6 +19,7 @@ class PublishFileType(Enum):
     VECTOR = 'vector'
     RASTER = 'raster'
     MODEL3D = 'model3d'
+    Tiles3D = 'tiles3d'
 
 class FileType(Enum):
     Compressed = 'Compressed'
@@ -36,6 +37,7 @@ class FileType(Enum):
     FileGDB = 'FileGDB'
     GeoTIFF = 'GeoTIFF'
     GeoJSON = 'GeoJSON'
+    ThreedTiles = 'ThreedTiles'
 
 class FileFormat(Enum):
     # Spatial Data Formats

{geobox-1.3.3 → geobox-1.4.0}/geobox/file.py

@@ -429,6 +429,9 @@ class File(Base):
                         FileType(self.layers[0]['format']).value in ['GLB']):
                 publish_as = PublishFileType.MODEL3D
 
+            elif self.file_type.value in ['ThreedTiles']:
+                publish_as = PublishFileType.Tiles3D
+
             else:
                 raise ValidationError('Unknown format')
 

geobox-1.4.0/geobox/layout.py

@@ -0,0 +1,314 @@
+from typing import List, Dict, Optional, TYPE_CHECKING, Union
+
+from .base import Base
+
+if TYPE_CHECKING:
+    from . import GeoboxClient
+    from .user import User
+
+class Layout(Base):
+
+    BASE_ENDPOINT = 'layouts/'
+
+    def __init__(self, 
+                 api: 'GeoboxClient', 
+                 uuid: str,
+                 data: Optional[Dict] = {}):
+        """
+        Initialize a layout instance.
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            uuid (str): The unique identifier for the layout.
+            data (Dict): The data of the layout.
+        """
+        super().__init__(api, uuid=uuid, data=data)
+
+
+    @classmethod
+    def get_layouts(cls, api: 'GeoboxClient', **kwargs) -> Union[List['Layout'], int]:
+        """
+        Get list of layouts with optional filtering and pagination.
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+
+        Keyword Args:
+            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 layouts. default is False.
+
+        Returns:
+            List[Layout] | int: A list of layout instances or the total number of layouts.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layouts = Layout.get_layout(client, q="name LIKE '%My layout%'")
+            or
+            >>> layouts = client.get_layout(q="name LIKE '%My layout%'")
+        """
+        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: Layout(api, item['uuid'], item))
+    
+
+    @classmethod
+    def create_layout(cls, 
+                     api: 'GeoboxClient', 
+                     name: str, 
+                     display_name: str = None, 
+                     description: str = None, 
+                     settings: Dict = {}, 
+                     thumbnail: str = None, 
+                     user_id: int = None) -> 'Layout':
+        """
+        Create a new layout.
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            name (str): The name of the Layout.
+            display_name (str): The display name of the layout.
+            description (str): The description of the layout.
+            settings (Dict): The settings of the layout.
+            thumbnail (str): The thumbnail of the layout.
+            user_id (int): Specific user. privileges layout.
+
+        Returns:
+            Layout: The newly created layout instance.
+
+        Raises:
+            ValidationError: If the layout data is invalid.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.create_layout(client, name="my_layout")
+            or
+            >>> layout = client.create_layout(name="my_layout")
+        """
+        data = {
+            "name": name,
+            "display_name": display_name,
+            "description": description,
+            "settings": settings,
+            "thumbnail": thumbnail,
+            "user_id": user_id,
+        }
+        return super()._create(api, cls.BASE_ENDPOINT, data, factory_func=lambda api, item: Layout(api, item['uuid'], item))
+
+    
+    @classmethod
+    def get_layout(cls, api: 'GeoboxClient', uuid: str, user_id: int = None) -> 'Layout':
+        """
+        Get a layout by its UUID.
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            uuid (str): The UUID of the layout to get.
+            user_id (int): Specific user. privileges required.
+
+        Returns:
+            Layout: The layout object.
+
+        Raises:
+            NotFoundError: If the layout with the specified UUID is not found.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            or
+            >>> layout = client.get_layout(uuid="12345678-1234-5678-1234-567812345678")
+        """
+        params = {
+            'f': 'json',
+            'user_id': user_id,
+        }
+        return super()._get_detail(api, cls.BASE_ENDPOINT, uuid, params, factory_func=lambda api, item: Layout(api, item['uuid'], item))
+
+
+    @classmethod
+    def get_layout_by_name(cls, api: 'GeoboxClient', name: str, user_id: int = None) -> Union['Layout', None]:
+        """
+        Get a layout by name
+
+        Args:
+            api (GeoboxClient): The GeoboxClient instance for making requests.
+            name (str): the name of the layout to get
+            user_id (int, optional): specific user. privileges required.
+
+        Returns:
+            Layout | None: returns the layout if a layout matches the given name, else None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout_by_name(client, name='test')
+            or
+            >>> layout = client.get_layout_by_name(name='test')
+        """
+        layouts = cls.get_layouts(api, q=f"name = '{name}'", user_id=user_id)
+        if layouts and layouts[0].name == name:
+            return layouts[0]
+        else:
+            return None
+
+
+    def update(self, **kwargs) -> Dict:
+        """
+        Update the layout.
+
+        Keyword Args:
+            name (str): The name of the layout.
+            display_name (str): The display name of the layout.
+            description (str): The description of the layout.
+            settings (Dict): The settings of the layout.
+            thumbnail (str): The thumbnail of the layout.
+
+        Returns:
+            Dict: The updated layout data.
+
+        Raises:
+            ValidationError: If the layout data is invalid.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> layout.update_layout(display_name="New Display Name")
+        """
+        data = {
+            "name": kwargs.get('name'),
+            "display_name": kwargs.get('display_name'),   
+            "description": kwargs.get('description'),
+            "settings": kwargs.get('settings'),
+            "thumbnail": kwargs.get('thumbnail')
+        }
+        return super()._update(self.endpoint, data)
+    
+
+    def delete(self) -> None:
+        """
+        Delete the Layout.
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> layout.delete()
+        """
+        super().delete(self.endpoint)
+
+
+    @property
+    def thumbnail(self) -> str:
+        """
+        Get the thumbnail URL of the Layout.
+
+        Returns:
+            str: The thumbnail of the Layout.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> layout.thumbnail
+            'https://example.com/thumbnail.png'
+        """
+        return super().thumbnail()
+    
+
+    def share(self, users: List['User']) -> None:
+        """
+        Shares the layout with specified users.
+
+        Args:
+            users (List[User]): The list of user objects to share the layout with.
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import GeoboxClient             
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> users = client.search_users(search='John')
+            >>> layout.share(users=users)
+        """
+        super()._share(self.endpoint, users)
+    
+
+    def unshare(self, users: List['User']) -> None:
+        """
+        Unshares the layout with specified users.
+
+        Args:
+            users (List[User]): The list of user objects to unshare the layout with.
+
+        Returns:
+            None
+
+        Example:
+            >>> from geobox import GeoboxClient             
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> users = client.search_users(search='John')
+            >>> layout.unshare(users=users)
+        """
+        super()._unshare(self.endpoint, users)
+
+
+    def get_shared_users(self, search: str = None, skip: int = 0, limit: int = 10) -> List['User']:
+        """
+        Retrieves the list of users the layout is shared with.
+
+        Args:
+            search (str, optional): The search query.
+            skip (int, optional): The number of users to skip.
+            limit (int, optional): The maximum number of users to retrieve.
+
+        Returns:
+            List[User]: The list of shared users.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.layout import Layout
+            >>> client = GeoboxClient()
+            >>> layout = Layout.get_layout(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> layout.get_shared_users(search='John', skip=0, limit=10)
+        """
+        params = {
+            'search': search,
+            'skip': skip,
+            'limit': limit
+        }
+        return super()._get_shared_users(self.endpoint, params)

{geobox-1.3.3 → geobox-1.4.0}/geobox/map.py

@@ -2,7 +2,7 @@ from typing import Dict, List, Optional, Union, TYPE_CHECKING
 from urllib.parse import urljoin, urlencode
 
 from .base import Base
-from .utils import clean_data
+from .utils import clean_data, join_url_params
 from .model3d import Model
 
 if TYPE_CHECKING:
@@ -276,8 +276,7 @@ class Map(Base):
             >>> map.thumbnail
             'https://example.com/thumbnail.png'
         """
-        endpoint = f"{self.api.base_url}{self.endpoint}thumbnail.png"
-        return endpoint
+        return super().thumbnail()
     
 
     def set_readonly(self, readonly: bool) -> None:
@@ -351,6 +350,10 @@ class Map(Base):
         endpoint = urljoin(self.api.base_url, f'{self.endpoint}wmts/')
         if scale:
             endpoint = f"{endpoint}?scale={scale}"
+
+        if not self.api.access_token and self.api.apikey:
+            endpoint = join_url_params(endpoint, {"apikey": self.api.apikey})
+
         return endpoint
 
     
@@ -856,4 +859,43 @@ class Map(Base):
             >>> map.image_tile_url()
             >>> map.image_tile_url(x=1, y=2, z=3, format='.pbf')
         """
-        return f"{self.BASE_ENDPOINT}{self.endpoint}{z}/{x}/{y}{format}"
+        endpoint = f"{self.api.base_url}{self.endpoint}tiles/{z}/{x}/{y}{format}"
+
+        if not self.api.access_token and self.api.apikey:
+            endpoint = f'{endpoint}?apikey={self.api.apikey}'
+
+        return endpoint
+    
+
+    def export_map_to_image(self, bbox: List, width: int, height: int) -> 'Task':
+        """
+        Export the map to image
+
+        Args:
+            bbox (List): e.g. [50.275, 35.1195, 51.4459, 36.0416]
+            width (int): minimum: 10, maximum: 10000
+            height (int): minimum: 10, maximum: 10000
+
+        Returns:
+            Task: the task object
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.map import Map
+            >>> client = GeoboxClient()
+            >>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
+            >>> task = map.export_map_to_image(bbox=[50.275, 35.1195, 51.4459, 36.0416],
+            ...                                 width=1024,
+            ...                                 height=1024)
+        """
+        data = clean_data({
+            'uuid': self.uuid,
+            'bbox': bbox,
+            'width': width,
+            'height': height
+        })
+        query_string = urlencode(data)
+        endpoint = urljoin(self.endpoint, 'export/')
+        endpoint = f"{endpoint}?{query_string}"
+        response = self.api.post(endpoint)
+        return self.api.get_task(response['task_id'])