Merge pull request #7 from jplacht/feat-storage

Add FIO storage endpoints

docs/endpoints/storage.md

@@ -0,0 +1,14 @@
+Exposes FIO Storage data for users.
+All storage data requires a **FIO API KEY**. You will need to have access to the data the user has in FIO in order to access it.
+
+Example:
+```python
+from fio_wrapper import FIO
+
+fio = FIO(api_key="your_api_key")
+
+# Get users storage data
+user_storage = fio.Sites.get(username="PrUn username")
+```
+
+::: endpoints.endpoints_v1.storage

fio_wrapper/endpoints/abstracts/abstract_sites.py

@@ -2,5 +2,8 @@ class AbstractSites:
     def get(self, username: str):
         raise NotImplemented()
 
+    def get_planet(self, username: str, planet: str):
+        raise NotImplemented()
+
     def planets(self, username: str):
         raise NotImplemented()

fio_wrapper/endpoints/abstracts/abstract_storage.py

@@ -0,0 +1,9 @@
+class AbstractStorage:
+    def get(self, username: str):
+        raise NotImplemented()
+
+    def get_specific(self, username: str, specific: str):
+        raise NotImplemented()
+
+    def planets(self, username: str):
+        raise NotImplemented()

fio_wrapper/endpoints/endpoints_v1/sites.py

@@ -105,6 +105,21 @@ def planets(self, username: str) -> List[str]:
 
     @apikey_required
     def warehouses(self, username: str) -> WarehouseList:
+        """Get warehouse data for username from FIO
+
+        Note:
+            FIO API Key Required
+
+        Args:
+            username (str): Prosperous Universe username
+
+        Raises:
+            NoSiteData: Username has no warehouse site data
+            NotAuthenticated: Not authenticated or no appropiate permissions
+
+        Returns:
+            WarehouseList: List of Warehouses
+        """
         (status, data) = self._adapter.get(
             endpoint=self._adapter.urls.sites_warehouses_get(username=username),
             err_codes=[204, 401],

fio_wrapper/endpoints/endpoints_v1/storage.py

@@ -0,0 +1,100 @@
+from typing import List
+from fio_wrapper.decorator import apikey_required
+from fio_wrapper.endpoints.abstracts.abstract_endpoint import AbstractEndpoint
+from fio_wrapper.endpoints.abstracts.abstract_storage import AbstractStorage
+from fio_wrapper.exceptions import NoStorageData, NotAuthenticated
+from fio_wrapper.models.storage_models import StorageList, Storage as StorageModel
+
+
+class Storage(AbstractStorage, AbstractEndpoint):
+    @apikey_required
+    def get(self, username: str) -> StorageList:
+        """Gets users storage data from FIO
+
+        Note:
+            FIO API Key Required
+
+        Args:
+            username (str): Prosperous Universe username
+
+        Raises:
+            NoStorageData: Username has no storage data
+            NotAuthenticated: Not authenticated or no appropiate permissions
+
+        Returns:
+            StorageList: List of storages
+        """
+        (status, data) = self._adapter.get(
+            endpoint=self._adapter.urls.storage_get_url(username=username),
+            err_codes=[204, 401],
+        )
+
+        if status == 200:
+            return StorageList.model_validate(data)
+
+        elif status == 204:
+            raise NoStorageData("Username has no storage data")
+        elif status == 401:
+            raise NotAuthenticated("Not authenticated or no appropiate permissions")
+
+    @apikey_required
+    def get_specific(self, username: str, specific: str) -> StorageModel:
+        """Gets users specific storage data from FIO
+
+        Note:
+            FIO API Key Required
+
+        Args:
+            username (str): Prosperous Universe username
+            specific (str): StorageId, PlanetId, PlanetNaturalId or PlanetName
+
+        Raises:
+            NoStorageData: Username has no storage data
+            NotAuthenticated: Not authenticated or no appropiate permissions
+
+        Returns:
+            StorageModel: Storage data
+        """
+        (status, data) = self._adapter.get(
+            endpoint=self._adapter.urls.storage_get_specific_url(
+                username=username, specific=specific
+            ),
+            err_codes=[204, 401],
+        )
+
+        if status == 200:
+            return StorageModel.model_validate(data)
+
+        elif status == 204:
+            raise NoStorageData("Username has no storage data")
+        elif status == 401:
+            raise NotAuthenticated("Not authenticated or no appropiate permissions")
+
+    @apikey_required
+    def planets(self, username: str) -> List[str]:
+        """Returns a list of storages from FIO
+
+        Note:
+            FIO API Key Required
+
+        Args:
+            username (str): Prosperous Universe username
+
+        Raises:
+            NoStorageData: Username has no storage data
+            NotAuthenticated: Not authenticated or no appropiate permissions
+
+        Returns:
+            List[str]: List of StorageIds
+        """
+        (status, data) = self._adapter.get(
+            endpoint=self._adapter.urls.storage_planets_get_url(username=username),
+            err_codes=[204, 401],
+        )
+
+        if status == 200:
+            return data
+        elif status == 204:
+            raise NoStorageData("Username has no storage data")
+        elif status == 401:
+            raise NotAuthenticated("Not authenticated or no appropiate permissions")

fio_wrapper/exceptions.py

@@ -125,3 +125,12 @@ class NoSiteData(Exception):
     """No site data found"""
 
     pass
+
+
+# Storage
+
+
+class NoStorageData(Exception):
+    """No storage data found"""
+
+    pass

fio_wrapper/fio.py

@@ -11,6 +11,7 @@
 from fio_wrapper.endpoints.endpoints_v1 import planet as planet_v1
 from fio_wrapper.endpoints.endpoints_v1 import recipe as recipe_v1
 from fio_wrapper.endpoints.endpoints_v1 import sites as sites_v1
+from fio_wrapper.endpoints.endpoints_v1 import storage as storage_v1
 
 
 class FIO:
@@ -23,6 +24,8 @@ class FIO:
         Material (Material): Material information
         Planet (Planet): Planet information
         Recipe (Recipe): Recipe information
+        Sites (Sites): Sites information
+        Storage (Storage): Storage information
     """
 
     def __init__(
@@ -53,6 +56,7 @@ def __init__(
             self.Planet = planet_v1.Planet(self._adapter)
             self.Recipe = recipe_v1.Recipe(self._adapter)
             self.Sites = sites_v1.Sites(self._adapter)
+            self.Storage = storage_v1.Storage(self._adapter)
 
         else:
             raise EndpointNotImplemented()

fio_wrapper/models/storage_models.py

@@ -0,0 +1,39 @@
+from typing import List, Optional
+from datetime import datetime
+from pydantic import BaseModel, RootModel, Field, NaiveDatetime
+
+
+class StorageItem(BaseModel):
+    MaterialId: str = Field(min_length=32)
+    MaterialName: Optional[str]
+    MaterialTicker: Optional[str] = Field(max_length=3, default=None)
+    MaterialCategory: Optional[str] = Field(min_length=32, default=None)
+    MaterialWeight: float
+    MaterialVolume: float
+    MaterialAmount: int
+    MaterialValue: float
+    MaterialValueCurrency: Optional[str]
+    Type: str
+    TotalWeight: float
+    TotalVolume: float
+
+
+class Storage(BaseModel):
+    StorageItems: Optional[List[StorageItem]]
+    StorageId: str = Field(min_length=32)
+    AddressableId: str = Field(min_length=32)
+    Name: Optional[str]
+    Type: str
+    UserNameSubmitted: str
+    Timestamp: datetime
+    WeightCapacity: int
+    VolumeCapacity: int
+    UserNameSubmitted: str
+    Timestamp: NaiveDatetime
+
+
+class StorageList(RootModel):
+    root: List[Storage]
+
+    def __iter__(self):
+        return iter(self.root)

fio_wrapper/urls.py

@@ -39,6 +39,10 @@ def __init__(self, base_url: str) -> None:
         self.sites_planets = "/planets"
         self.sites_warehouses = "/warehouses"
 
+        # storage
+        self.storage_base = "/storage"
+        self.storage_planets = "/planets"
+
     # Material
     def material_url(self) -> str:
         return self.base_url + self.material_base
@@ -168,3 +172,16 @@ def sites_planets_get_planet_url(self, username: str, planet: str) -> str:
 
     def sites_warehouses_get(self, username: str) -> str:
         return self.sites_url() + self.sites_warehouses + "/" + username
+
+    # Storage
+    def storage_url(self) -> str:
+        return self.base_url + self.storage_base
+
+    def storage_get_url(self, username: str) -> str:
+        return self.storage_url() + "/" + username
+
+    def storage_planets_get_url(self, username: str) -> str:
+        return self.storage_url() + self.storage_planets + "/" + username
+
+    def storage_get_specific_url(self, username: str, specific: str) -> str:
+        return self.storage_url() + "/" + username + "/" + specific

mkdocs.yml

@@ -84,12 +84,13 @@ nav:
     - Decorators: decorator.md
     - Exceptions: exception.md
   - Endpoints (FIO v.1): 
-    - Planet: 'endpoints/planet.md'
     - Building: 'endpoints/building.md'
-    - Recipe: 'endpoints/recipe.md'
-    - Material: 'endpoints/material.md'
     - Exchange: 'endpoints/exchange.md'
     - LocalMarket: 'endpoints/localmarket.md'
+    - Material: 'endpoints/material.md'
+    - Planet: 'endpoints/planet.md'
+    - Recipe: 'endpoints/recipe.md'
     - Sites: 'endpoints/sites.md'
+    - Storage: 'endpoints/storage.md'
   - Test Coverage:
     - Coverage Report: coverage.md