geobox 2.2.6__py3-none-any.whl → 2.4.0__py3-none-any.whl

geobox/api.py

@@ -5,7 +5,7 @@ from urllib.parse import urljoin
 from typing import Dict, List, Optional, Union
 from datetime import datetime
 
-from geobox.enums import AnalysisDataType, AnalysisResampleMethod
+from geobox.enums import AnalysisDataType, AnalysisResampleMethod, RelationshipCardinality
 
 from .exception import AuthenticationError, ApiRequestError, NotFoundError, ValidationError, ServerError, AuthorizationError
 from .vectorlayer import VectorLayer, LayerType
@@ -35,6 +35,7 @@ from .attachment import Attachment
 from .apikey import ApiKey
 from .log import Log
 from .usage import Usage, UsageScale, UsageParam
+from .table import RelationshipEndpoint, Table, Relationship
 
 logger = logging.getLogger(__name__)
 
@@ -187,10 +188,10 @@ class GeoboxClient:
             >>> client = GeoboxClient(apikey="apikey")
             >>> client = GeoboxClient(access_token="access_token")
         """
-        self.username = os.getenv('GEOBOX_USERNAME') if os.getenv('GEOBOX_USERNAME') else username
-        self.password = os.getenv('GEOBOX_PASSWORD') if os.getenv('GEOBOX_PASSWORD') else password
-        self.access_token = os.getenv('GEOBOX_ACCESS_TOKEN') if os.getenv('GEOBOX_ACCESS_TOKEN') else access_token
-        self.apikey = os.getenv('GEOBOX_APIKEY') if os.getenv('GEOBOX_APIKEY') else apikey
+        self.username = username if username else os.getenv('GEOBOX_USERNAME')
+        self.password = password if password else os.getenv('GEOBOX_PASSWORD')
+        self.access_token = access_token if access_token else os.getenv('GEOBOX_ACCESS_TOKEN')
+        self.apikey = apikey if apikey else os.getenv('GEOBOX_APIKEY')
         self.verify = verify
         self.session = _RequestSession(access_token=self.access_token)
 
@@ -2638,3 +2639,262 @@ class GeoboxClient:
             >>> client.update_usage()
         """
         return Usage.update_usage(self, user_id=user_id)
+
+
+
+    def get_tables(self, **kwargs) -> Union[List['Table'], int]:
+        """
+        Get list of tables with optional filtering and pagination.
+
+        Keyword Args:
+            include_settings (bool): Whether to include table settings. default: False
+            temporary (bool): Whether to return temporary tables. default: False
+            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: False.
+            skip (int): Number of items to skip. default: 0
+            limit (int): Number of items to return. default: 10
+            user_id (int): Specific user. privileges required
+            shared (bool): Whether to return shared tables. default: False
+
+        Returns:
+            List[Table] | int: A list of table instances or the total number of tables.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> tables = client.get_tables(q="name LIKE '%My table%'")
+        """
+        return Table.get_tables(self, **kwargs)
+    
+
+    def create_table(self,
+        name: str, 
+        display_name: Optional[str] = None, 
+        description: Optional[str] = None, 
+        temporary: bool = False,
+        fields: Optional[List[Dict]] = None,
+    ) -> 'Table':
+        """
+        Create a new table.
+
+        Args:
+            name (str): The name of the Table.
+            display_name (str, optional): The display name of the table.
+            description (str, optional): The description of the table.
+            temporary (bool, optional): Whether to create a temporary tables. default: False
+            fields (List[Dict], optional): raw table fields. you can use add_field method for simpler and safer field addition. required dictionary keys: name, datatype
+
+        Returns:
+            Table: The newly created table instance.
+
+        Raises:
+            ValidationError: If the table data is invalid.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> table = client.create_table(name="my_table")
+        """
+        return Table.create_table(self,
+            name=name,
+            display_name=display_name,
+            description=description,
+            temporary=temporary,
+            fields=fields,
+        )
+    
+
+    def get_table(self, 
+        uuid: str, 
+        user_id: int = None,
+    ) -> 'Table':
+        """
+        Get a table by UUID.
+
+        Args:
+            uuid (str): The UUID of the table to get.
+            user_id (int): Specific user. privileges required.
+
+        Returns:
+            Table: The Table object.
+
+        Raises:
+            NotFoundError: If the table with the specified UUID is not found.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> table = client.get_table(uuid="12345678-1234-5678-1234-567812345678")
+        """
+        return Table.get_table(self, uuid, user_id)
+
+
+    def get_table_by_name(self, 
+        name: str, 
+        user_id: int = None,
+    ) -> Union['Table', None]:
+        """
+        Get a table by name
+
+        Args:
+            name (str): the name of the table to get
+            user_id (int, optional): specific user. privileges required.
+
+        Returns:
+            Table | None: returns the table if a table matches the given name, else None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> table = client.get_table_by_name(name='test')
+
+        """
+        return Table.get_table_by_name(self, name, user_id)
+
+
+    def get_relationships(
+        self,
+        **kwargs,
+    ) -> Union[List['Relationship'], int]:
+        """
+        Get a list of relationships 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: False.
+            skip (int): Number of items to skip. default: 0
+            limit (int): Number of items to return. default: 10
+            user_id (int): Specific user. privileges required
+            shared (bool): Whether to return shared tables. default: False
+
+        Returns:
+            List[Relationship] | int: A list of relationship instances or the total number of relationships.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.table import Relatinship
+            >>> client = GeoboxClient()
+            >>> relationships = client.get_relationships(q="name LIKE '%My relationship%'")
+        """
+        return Relationship.get_relationships(self, **kwargs)
+
+
+    def create_relationship(
+        self,
+        name: str,
+        cardinality: 'RelationshipCardinality',
+        *,
+        source: 'RelationshipEndpoint',
+        target: 'RelationshipEndpoint',
+        relation_table: Optional['Table'] = None,
+        display_name: Optional[str] = None,
+        description: Optional[str] = None,
+        user_id: Optional[int] = None,
+    ) -> 'Relationship':
+        """
+        Create a new Relationship
+
+        Args:
+            name (str): name of the relationship
+            cardinality (RelationshipCardinality): One to One, One to Many, or Many to Many
+            
+        Keyword Args:
+            source (RelationshipEndpoint): Definition of the source side of the relationship, including the table (or layer), field, and foreign-key field
+            target (RelationshipEndpoint): Definition of the target side of the relationship, including the table (or layer), field, and foreign-key field
+            relation_table (Table, optional): The table that stores the relationship metadata or join records. (Required for Many-to-Many relationships)
+            display_name (str, optional): Human-readable name for the relationship
+            description (str, optional): the description of the relationship
+            user_id (int, optional): Specific user. privileges required.
+
+        Returns:
+            Relationship: a relationship instance
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.table import RelationshipEndpoint, RelationshipCardinality
+            >>> client = GeoboxClient()
+            >>> source = RelationshipEndpoint(
+            ...     table=client.get_table_by_name('owner'),
+            ...     field="name", # on source table
+            ...     fk_field="book_name", # on relation table
+            ... )
+            >>> target = RelationshipEndpoint(
+            ...     table=client.get_table_by_name('parcel'),
+            ...     field="name", # on target table
+            ...     fk_field="author_name", # on relation table
+            ... )
+            >>> relationship = client.create_relationship(
+            ...     name="owner_parcel",
+            ...     cardinality=RelationshipCardinality.ManytoMany,
+            ...     source=source,
+            ...     target=target,
+            ...     relation_table=client.get_table_by_name('owner_parcel'),
+            ... )
+        """ 
+        return Relationship.create_relationship(
+            self,
+            name=name,
+            cardinality=cardinality,
+            source=source,
+            target=target,
+            relation_table=relation_table,
+            display_name=display_name,
+            description=description,
+            user_id=user_id,
+        )
+
+
+    def get_relationship(
+        self,
+        uuid: str,
+        user_id: Optional[int] = None,
+    ) -> 'Relationship':
+        """
+        Get a relationship by UUID.
+
+        Args:
+            uuid (str): The UUID of the relationship to get.
+            user_id (int, optional): Specific user. privileges required.
+
+        Returns:
+            Relationship: The Relationship object.
+
+        Raises:
+            NotFoundError: If the Relationship with the specified UUID is not found.
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
+        """
+        return Relationship.get_relationship(
+            self,
+            uuid=uuid,
+            user_id=user_id,
+        )
+
+
+    def get_relationship_by_name(self, name: str, user_id: int = None) -> Union['Relationship', None]:
+        """
+        Get a relationship by name
+
+        Args:
+            name (str): the name of the relationship to get
+            user_id (int, optional): specific user. privileges required.
+
+        Returns:
+            Relationship | None: returns the relationship if a relationship matches the given name, else None
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> from geobox.relationship import Relationship
+            >>> client = GeoboxClient()
+            >>> relationship = client.get_relationship_by_name(name='test')
+        """
+        return Relationship.get_relationship_by_name(self, name=name, user_id=user_id)

geobox/apikey.py

@@ -6,8 +6,6 @@ from .utils import clean_data
 
 if TYPE_CHECKING:
     from . import GeoboxClient
-    from .aio import AsyncGeoboxClient
-    from .aio.apikey import AsyncApiKey
 
 
 class ApiKey(Base):
@@ -237,27 +235,3 @@ class ApiKey(Base):
         endpoint = f"{self.endpoint}/grant"
         self.api.post(endpoint)
         self.data['revoked'] = False
-
-
-    def to_async(self, async_client: 'AsyncGeoboxClient') -> 'AsyncApiKey':
-        """
-        Switch to async version of the apikey instance to have access to the async methods
-
-        Args:
-            async_client (AsyncGeoboxClient): The async version of the GeoboxClient instance for making requests.
-
-        Returns:
-            AsyncApiKey: the async instance of the apikey.
-
-        Example:
-            >>> from geobox import Geoboxclient
-            >>> from geobox.aio import AsyncGeoboxClient
-            >>> from geobox.apikey import ApiKey
-            >>> client = GeoboxClient()
-            >>> apikey = ApiKey.get_apikey(client, key_id=1)
-            >>> async with AsyncGeoboxClient() as async_client:
-            >>>     async_apikey = apikey.to_async(async_client)
-        """
-        from .aio.apikey import AsyncApiKey
-
-        return AsyncApiKey(api=async_client, key_id=self.key_id, data=self.data)

geobox/attachment.py

@@ -11,8 +11,6 @@ from .file import File
 if TYPE_CHECKING:
     from . import GeoboxClient 
     from .feature import Feature
-    from .aio import AsyncGeoboxClient
-    from .aio.attachment import AsyncAttachment
 
 
 class Attachment(Base):
@@ -311,27 +309,3 @@ class Attachment(Base):
             >>> attachment.thumbnail
         """
         return super()._thumbnail(format='')
-    
-
-    def to_async(self, async_client: 'AsyncGeoboxClient') -> 'AsyncAttachment':
-        """
-        Switch to async version of the attachment instance to have access to the async methods
-
-        Args:
-            async_client (AsyncGeoboxClient): The async version of the GeoboxClient instance for making requests.
-
-        Returns:
-            AsyncAttachment: the async instance of the attachment.
-
-        Example:
-            >>> from geobox import Geoboxclient
-            >>> from geobox.aio import AsyncGeoboxClient
-            >>> from geobox.attachment import Attachment
-            >>> client = GeoboxClient()
-            >>> attachment = Attachment.get_attachment(client, uuid="12345678-1234-5678-1234-567812345678")
-            >>> async with AsyncGeoboxClient() as async_client:
-            >>>     async_attachment = attachment.to_async(async_client)
-        """
-        from .aio.attachment import AsyncAttachment
-
-        return AsyncAttachment(api=async_client, attachment_id=self.attachment_id, data=self.data)

geobox/basemap.py

@@ -7,8 +7,6 @@ from .utils import clean_data
 
 if TYPE_CHECKING:
     from . import GeoboxClient
-    from .aio import AsyncGeoboxClient
-    from .aio.basemap import AsyncBasemap
     
 
 class Basemap(Base):
@@ -167,29 +165,3 @@ class Basemap(Base):
         query_string = urlencode(param)
         endpoint = urljoin(cls.BASE_ENDPOINT, f"?{query_string}")
         api.get(endpoint)
-
-
-    def to_async(self, async_client: 'AsyncGeoboxClient') -> 'AsyncBasemap':
-        """
-        Switch to async version of the basemap instance to have access to the async methods
-
-        Args:
-            async_client (AsyncGeoboxClient): The async version of the GeoboxClient instance for making requests.
-
-        Returns:
-            AsyncBasemap: the async instance of the basemap.
-
-        Example:
-            >>> from geobox import Geoboxclient
-            >>> from geobox.aio import AsyncGeoboxClient
-            >>> from geobox.basemap import Basemap
-            >>> client = GeoboxClient()
-            >>> basemap = Basemap.get_basemap(client, name='test')
-            or
-            >>> basemap = client.get_basemap(name='test')
-            >>> async with AsyncGeoboxClient() as async_client:
-            >>>     async_basemap = basemap.to_async(async_client)
-        """
-        from .aio.basemap import AsyncBasemap
-
-        return AsyncBasemap(api=async_client, data=self.data)

geobox/dashboard.py

@@ -5,8 +5,6 @@ from .base import Base
 if TYPE_CHECKING:
     from . import GeoboxClient
     from .user import User
-    from .aio import AsyncGeoboxClient
-    from .aio.dashboard import AsyncDashboard
 
 
 class Dashboard(Base):
@@ -314,27 +312,3 @@ class Dashboard(Base):
             'limit': limit
         }
         return super()._get_shared_users(self.endpoint, params)
-
-
-    def to_async(self, async_client: 'AsyncGeoboxClient') -> 'AsyncDashboard':
-        """
-        Switch to async version of the dashboard instance to have access to the async methods
-
-        Args:
-            async_client (AsyncGeoboxClient): The async version of the GeoboxClient instance for making requests.
-
-        Returns:
-            AsyncDashboard: the async instance of the dashboard.
-
-        Example:
-            >>> from geobox import Geoboxclient
-            >>> from geobox.aio import AsyncGeoboxClient
-            >>> from geobox.dashboard import Dashboard
-            >>> client = GeoboxClient()
-            >>> dashboard = Dashboard.get_dashboard(client, uuid="12345678-1234-5678-1234-567812345678")
-            >>> async with AsyncGeoboxClient() as async_client:
-            >>>     async_dashboard = dashboard.to_async(async_client)
-        """
-        from .aio.dashboard import AsyncDashboard
-
-        return AsyncDashboard(api=async_client, uuid=self.uuid, data=self.data)

geobox/enums.py

@@ -228,6 +228,10 @@ class QueryParamType(Enum):
     """
     A layer parameter.
     """
+    TABLE = "Table"
+    """
+    A table parameter.
+    """
     ATTRIBUTE = "Attribute"
     """
     A Attribute parameter.
@@ -429,4 +433,14 @@ class SpatialPredicate(Enum):
     EQUAL = 'Equal'
     OVERLAP = 'Overlap'
     TOUCH = 'Touch'
-    WITHIN = 'Within'
+    WITHIN = 'Within'
+
+
+class TableExportFormat(Enum):
+    CSV = 'CSV'
+
+
+class RelationshipCardinality(Enum):
+    OnetoOne = '1-1'
+    OnetoMany = '1-M'
+    ManytoMany = 'M-N'

geobox/feature.py

@@ -1,13 +1,12 @@
 from urllib.parse import urljoin
-from typing import Optional, List, Dict, Any, TYPE_CHECKING
+from typing import Optional, List, Dict, Any, TYPE_CHECKING, Union
 
 from .base import Base
 from .enums import FeatureType
 
 if TYPE_CHECKING:
     from .vectorlayer import VectorLayer
-    from .aio import AsyncGeoboxClient
-    from .aio.feature import AsyncFeature
+    from .table import Table, TableRow, Relationship
 
 
 class Feature(Base):
@@ -545,26 +544,182 @@ class Feature(Base):
         return self
 
 
-    def to_async(self, async_client: 'AsyncGeoboxClient') -> 'AsyncFeature':
+    def _get_other_side_of_relationship(
+        self, 
+        relationship: 'Relationship',
+    ) -> Union['Table', 'VectorLayer']:
         """
-        Switch to async version of the feature instance to have access to the async methods
+        Determine which side of a relationship this table is on and return the opposite side.
+        
+        Used internally to navigate bidirectional relationships.
+        
+        Args:
+            relationship (Relationship): The relationship to examine.
+            
+        Returns:
+            Table | VectorLayer: The endpoint (table or layer) on the opposite side
+            of the relationship from this table.
+            
+        Raises:
+            ValueError: If this table is not part of the given relationship.
+            
+        Note:
+            This method assumes the table is either the source or target,
+            not the relation table in Many-to-Many relationships.
+        """
+        if relationship.source_id == self.layer.id:
+            return relationship.get_target()
+
+        if relationship.target_id == self.layer.id:
+            return relationship.get_source()
 
+        raise ValueError("Relationship does not involve this table.")
+
+
+    def _fetch_related_from_target(
+        self, 
+        target: Union['Table', 'VectorLayer'], 
+        relationship_uuid: str,
+    ) -> Union[List['TableRow'], List['Feature']]:
+        """
+        Fetch related rows/features from a relationship target.
+        
+        Internal helper that dispatches to the appropriate API method
+        based on target type.
+        
         Args:
-            async_client (AsyncGeoboxClient): The async version of the GeoboxClient instance for making requests.
+            target (Table | VectorLayer): The target endpoint (Table or VectorLayer) to query.
+            relationship_uuid (str): UUID of the relationship to traverse.
+            
+        Raises:
+            TypeError: If target is not a Table or VectorLayer.
 
         Returns:
-            AsyncFeature: the async instance of the feature.
+            List[TableRow] | List[Feature]: Related rows or features.
+        """
+        from .table import Table
+        from .vectorlayer import VectorLayer
+
+        if isinstance(target, Table):
+            return target.get_rows(
+                relationship_uuid=relationship_uuid,
+                related_record_id=self.id,
+            )
+
+        if isinstance(target, VectorLayer):
+            return target.get_features(
+                relationship_uuid=relationship_uuid,
+                related_record_id=self.id,
+            )
+
+        raise TypeError(f"Unsupported target type: {type(target)}")
+
+
+    def get_related_records(self,
+        relationship_uuid: str,
+    ) -> Union[List['TableRow'], List['Feature']]:
+        """
+        Get the related records on the *other side* of the relationship that are linked to this row
+
+        Args:
+            relationship_uuid (str): The uuid of relationship
+
+        Returns:
+            List[TableRow] | List[Feature]: a list of the related records
+
+        Raises:
+            ValueError:
+                If the given relationship does not involve the current table
+                (i.e., this row is neither the source nor the target of the relationship).
+
+            TypeError:
+                If the relationship target type is not supported for fetching
+                related records.
 
         Example:
-            >>> from geobox import Geoboxclient
-            >>> from geobox.aio import AsyncGeoboxClient
+            >>> from geobox import GeoboxClient
             >>> client = GeoboxClient()
             >>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
-            >>> feature = layer.get_feature(id=1, srid=3857)
-            >>> async with AsyncGeoboxClient() as async_client:
-            >>>     async_feature = feature.to_async(async_client)
+            >>> feature = layer.get_feature(feature_id=1)
+            >>> related_records = feature.get_related_records(relationship_uuid="12345678-1234-5678-1234-567812345678")
         """
-        from .aio.feature import AsyncFeature
+        relationship = self.api.get_relationship(relationship_uuid)
+
+        other_side = self._get_other_side_of_relationship(relationship)
+
+        return self._fetch_related_from_target(
+            target=other_side,
+            relationship_uuid=relationship_uuid,
+        )
+
+
+    def associate_with(
+        self,
+        relationship_uuid: str,
+        *,
+        target_ids: Optional[List[int]] = None,
+        q: Optional[str] = None,
+    ) -> Dict:
+        """
+        Create relationships between the source record and target records
+
+        Args:
+            relationship_uuid (str): the relationship uuid
+            target_ids (List[int], optional): a list of target record ids to be associated with the current record
+            q (str, optional): query filter on target layer or table to select which target features or rows that are going to be related to the current record
+
+        Returns:
+            Dict: the record association result
 
-        async_layer = self.layer.to_async(async_client=async_client)
-        return AsyncFeature(layer=async_layer, srid=self.srid, data=self.data)
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
+            >>> feature = layer.get_feature(feature_id=1)
+            >>> feature.associate_with(
+            ...     relationship_uuid="12345678-1234-5678-1234-567812345678",
+            ...     target_ids=[1, 2, 3],
+            ... )
+        """
+        relationship = self.api.get_relationship(uuid=relationship_uuid)
+        return relationship.associate_records(
+            source_id=self.id,
+            target_ids=target_ids,
+            q=q,
+        )
+
+
+    def disassociate_with(
+        self,
+        relationship_uuid: str,
+        *,
+        target_ids: Optional[List[int]] = None,
+        q: Optional[str] = None,
+    ) -> Dict:
+        """
+        Remove relationships between the source record and target records
+
+        Args:
+            relationship_uuid (str): the relationship uuid
+            target_ids (List[int], optional): a list of target record ids to be disassociated with the current record
+            q (str, optional): query filter on target layer or table to select which target features or rows that are going to be related to the current record
+
+        Returns:
+            Dict: the record association result
+
+        Example:
+            >>> from geobox import GeoboxClient
+            >>> client = GeoboxClient()
+            >>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
+            >>> feature = layer.get_feature(feature_id=1)
+            >>> feature.disassociate_with(
+            ...     relationship_uuid="12345678-1234-5678-1234-567812345678",
+            ...     target_ids=[1, 2, 3],
+            ... )
+        """
+        relationship = self.api.get_relationship(uuid=relationship_uuid)
+        return relationship.disassociate_records(
+            source_id=self.id,
+            target_ids=target_ids,
+            q=q,
+        )