ezoff 0.1.0__tar.gz

ezoff-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

ezoff-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include requirements.txt
+include README.md
+include LICENSE

ezoff-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.1
+Name: ezoff
+Version: 0.1.0
+Summary: Python package that acts as a wrapper for the EZOffice API.
+Home-page: https://github.com/pepsimidamerica/ezoff
+Author: Jordan Maynor
+Author-email: jmaynor@pepsimidamerica.com
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+
+# ezo
+
+Python package for interacting with the EZOffice API
+
+## Installation
+
+Add as a git submodule for now. Intend on at some point making available as a proper package.
+
+## Usage
+
+Several environment variables are required for ezo to function.
+
+| Required? | Env Variable | Description |
+| --------- | ------------ | ----------- |
+| EZO_BASE_URL | Yes | Should be https://{companyname}.ezofficeinventory.com/ |
+| EZO_TOKEN | Yes | The access token used to authenticate requests |
+
+## Project Structure
+
+Project is split up into several files depending on what area of the EZOffice API is being dealt with. Purely for organizational purposes.
+
+### Assets
+
+### Groups
+
+### Locations
+
+### Members
+
+### Work Orders
+
+## Notes
+
+The documentation is mistaken on custom fields (insofar as filling them out when creating an object or updating the custom field on an already existing object). It says to put underscores in place of spaces in the field name, but this is incorrect. After testing the API, it appears it wants the actual name of the field with the spaces, not underscores. At least on members.
+
+Similarly, the documentation isn't exhaustive when it comes to listing the valid fields when creating or updating something. Frequently there are fields on the actual page that aren't mentioned in the EZOffice documentation. Throughout program I check for that keys provided are valid to prevent the API call from erroring out. Just have to add to list of valid key whenever we run into one.
+
+When wanting to clear a field out of its current value with an update function, generally the empty string ("") should be used.

ezoff-0.1.0/README.md

@@ -0,0 +1,38 @@
+# ezo
+
+Python package for interacting with the EZOffice API
+
+## Installation
+
+Add as a git submodule for now. Intend on at some point making available as a proper package.
+
+## Usage
+
+Several environment variables are required for ezo to function.
+
+| Required? | Env Variable | Description |
+| --------- | ------------ | ----------- |
+| EZO_BASE_URL | Yes | Should be https://{companyname}.ezofficeinventory.com/ |
+| EZO_TOKEN | Yes | The access token used to authenticate requests |
+
+## Project Structure
+
+Project is split up into several files depending on what area of the EZOffice API is being dealt with. Purely for organizational purposes.
+
+### Assets
+
+### Groups
+
+### Locations
+
+### Members
+
+### Work Orders
+
+## Notes
+
+The documentation is mistaken on custom fields (insofar as filling them out when creating an object or updating the custom field on an already existing object). It says to put underscores in place of spaces in the field name, but this is incorrect. After testing the API, it appears it wants the actual name of the field with the spaces, not underscores. At least on members.
+
+Similarly, the documentation isn't exhaustive when it comes to listing the valid fields when creating or updating something. Frequently there are fields on the actual page that aren't mentioned in the EZOffice documentation. Throughout program I check for that keys provided are valid to prevent the API call from erroring out. Just have to add to list of valid key whenever we run into one.
+
+When wanting to clear a field out of its current value with an update function, generally the empty string ("") should be used.

ezoff-0.1.0/ezoff/__init__.py

@@ -0,0 +1 @@
+from .ezoff import *

ezoff-0.1.0/ezoff/assets.py

@@ -0,0 +1,532 @@
+"""
+Covers everything related to fixed assets in EZOffice
+"""
+
+import os
+
+import requests
+
+from ezoff.auth import Decorators
+
+
+@Decorators.check_env_vars
+def get_all_assets() -> list[dict]:
+    """
+    Get assets
+    Recommended to use endpoint that takes a filter instead.
+    This endpoint can be slow as it returns all assets in the system. Potentially
+    several hundred pages of assets.
+    https://ezo.io/ezofficeinventory/developers/#api-retrive-assets
+    """
+
+    url = os.environ["EZO_BASE_URL"] + "assets.api"
+
+    page = 1
+    all_assets = []
+
+    while True:
+        params = {"page": page}
+
+        try:
+            response = requests.get(
+                url,
+                headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+                params=params,
+                data={
+                    "include_custom_fields": "true",
+                    "show_document_urls": "true",
+                    "show_image_urls": "true",
+                },
+                timeout=10,
+            )
+        except Exception as e:
+            print("Error, could not get assets from EZOfficeInventory: ", e)
+            raise Exception(
+                "Error, could not get assets from EZOfficeInventory: " + str(e)
+            )
+
+        if response.status_code != 200:
+            print(
+                f"Error {response.status_code}, could not get assets from EZOfficeInventory: ",
+                response.content,
+            )
+            break
+
+        data = response.json()
+
+        if "assets" not in data:
+            print(
+                f"Error, could not get assets from EZOfficeInventory: ",
+                response.content,
+            )
+            raise Exception(
+                f"Error, could not get assets from EZOfficeInventory: "
+                + str(response.content)
+            )
+
+        all_assets.extend(data["assets"])
+
+        if "total_pages" not in data:
+            print("Error, could not get total_pages from EZOfficeInventory: ", data)
+            break
+
+        if page >= data["total_pages"]:
+            break
+
+        page += 1
+
+    return all_assets
+
+
+@Decorators.check_env_vars
+def get_filtered_assets(filter: dict) -> list[dict]:
+    """
+    Get assets via filtering. Recommended to use this endpoint rather than
+    returning all assets.
+    """
+    if "status" not in filter:
+        raise ValueError("filter must have 'status' key")
+
+    url = os.environ["EZO_BASE_URL"] + "assets/filter.api"
+
+    page = 1
+    all_assets = []
+
+    while True:
+        params = {"page": page}
+        params.update(filter)
+
+        try:
+            response = requests.get(
+                url,
+                headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+                params=params,
+                data={
+                    "include_custom_fields": "true",
+                    "show_document_urls": "true",
+                    "show_image_urls": "true",
+                },
+                timeout=10,
+            )
+        except Exception as e:
+            print("Error, could not get assets from EZOfficeInventory: ", e)
+            raise Exception(
+                "Error, could not get assets from EZOfficeInventory: " + str(e)
+            )
+
+        if response.status_code != 200:
+            print(
+                f"Error {response.status_code}, could not get assets from EZOfficeInventory: ",
+                response.content,
+            )
+            break
+
+        data = response.json()
+
+        if "assets" not in data:
+            print(
+                f"Error, could not get assets from EZOfficeInventory: ",
+                response.content,
+            )
+            raise Exception(
+                f"Error, could not get assets from EZOfficeInventory: "
+                + str(response.content)
+            )
+
+        all_assets.extend(data["assets"])
+
+        if "total_pages" not in data:
+            print("Error, could not get total_pages from EZOfficeInventory: ", data)
+            break
+
+        if page >= data["total_pages"]:
+            break
+
+        page += 1
+
+    return all_assets
+
+
+@Decorators.check_env_vars
+def search_for_asset(search_term: str) -> list[dict]:
+    """
+    Search for an asset.
+    The equivalent of the search bar in the EZOfficeInventory UI.
+    May not return all assets that match the search term. Better to use
+    get_filtered_assets if you want to return all assets that match a filter.
+    https://ezo.io/ezofficeinventory/developers/#api-search-name
+    """
+
+    url = os.environ["EZO_BASE_URL"] + "search.api"
+
+    page = 1
+    all_assets = []
+
+    while True:
+        data = {
+            "page": page,
+            "search": search_term,
+            "facet": "FixedAsset",
+            "include_custom_fields": "true",
+            "show_document_urls": "true",
+            "show_image_urls": "true",
+            "show_document_details": "true",
+        }
+
+        try:
+            response = requests.get(
+                url,
+                headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+                data=data,
+                timeout=10,
+            )
+        except Exception as e:
+            print("Error, could not get assets from EZOfficeInventory: ", e)
+            raise Exception(
+                "Error, could not get assets from EZOfficeInventory: " + str(e)
+            )
+
+        if response.status_code != 200:
+            print(
+                f"Error {response.status_code}, could not get assets from EZOfficeInventory: ",
+                response.content,
+            )
+            break
+
+        data = response.json()
+
+        if "assets" not in data:
+            print(
+                f"Error, could not get assets from EZOfficeInventory: ",
+                response.content,
+            )
+            raise Exception(
+                f"Error, could not get assets from EZOfficeInventory: "
+                + str(response.content)
+            )
+
+        all_assets.extend(data["assets"])
+
+        if "total_pages" not in data:
+            break
+
+        if page >= data["total_pages"]:
+            break
+
+        page += 1
+
+    return all_assets
+
+
+@Decorators.check_env_vars
+def create_asset(asset: dict) -> dict:
+    """
+    Create an asset
+    https://ezo.io/ezofficeinventory/developers/#api-create-asset
+    """
+
+    # Required fields
+    if "fixed_asset[name]" not in asset:
+        raise ValueError("asset must have 'fixed_asset[name]' key")
+    if "fixed_asset[group_id]" not in asset:
+        raise ValueError("asset must have 'fixed_asset[group_id]' key")
+    if "fixed_asset[purchased_on]" not in asset:
+        raise ValueError("asset must have 'fixed_asset[purchased_on]' key")
+        # Also check that the date is in the correct format mm/dd/yyyy
+        try:
+            datetime.strptime(asset["fixed_asset[purchased_on]"], "%m/%d/%Y")
+        except ValueError:
+            raise ValueError(
+                "asset['fixed_asset[purchased_on]'] must be in the format mm/dd/yyyy"
+            )
+
+    # Remove any keys that are not valid
+    valid_keys = [
+        "fixed_asset[name]",
+        "fixed_asset[description]",
+        "fixed_asset[group_id]",
+        "fixed_asset[sub_group_id]",
+        "fixed_asset[purchased_on]",
+        "fixed_asset[location_id]",
+        "fixed_asset[image_url]",
+        "fixed_asset[document_urls][]",
+        "fixed_asset[identifier]",
+    ]
+
+    asset = {
+        k: v for k, v in asset.items() if k in valid_keys or k.startswith("cust_attr")
+    }
+
+    url = os.environ["EZO_BASE_URL"] + "assets.api"
+
+    try:
+        response = requests.post(
+            url,
+            headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+            data=asset,
+            timeout=10,
+        )
+    except Exception as e:
+        print("Error, could not create asset in EZOfficeInventory: ", e)
+        raise Exception("Error, could not create asset in EZOfficeInventory: " + str(e))
+
+    if response.status_code != 200:
+        print(
+            f"Error {response.status_code}, could not create asset in EZOfficeInventory: ",
+            response.content,
+        )
+        raise Exception(
+            f"Error {response.status_code}, could not create asset in EZOfficeInventory: "
+            + str(response.content)
+        )
+
+    return response.json()
+
+
+@Decorators.check_env_vars
+def update_asset(asset_id: int, asset: dict) -> dict:
+    """
+    Update an asset's details
+    https://ezo.io/ezofficeinventory/developers/#api-update-asset
+    """
+
+    # Remove any keys that are not valid
+    valid_keys = [
+        "fixed_asset[name]",
+        "fixed_asset[description]",
+        "fixed_asset[group_id]",
+        "fixed_asset[sub_group_id]",
+        "fixed_asset[identifier]",
+        "fixed_asset[purchased_on]",
+        "fixed_asset[location_id]",
+        "fixed_asset[image_url]",
+        "fixed_asset[document_urls][]",
+    ]
+
+    asset = {
+        k: v for k, v in asset.items() if k in valid_keys or k.startswith("cust_attr")
+    }
+
+    url = os.environ["EZO_BASE_URL"] + "assets/" + str(asset_id) + ".api"
+
+    try:
+        response = requests.put(
+            url,
+            headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+            data=asset,
+            timeout=10,
+        )
+    except Exception as e:
+        print("Error, could not update asset in EZOfficeInventory: ", e)
+        raise Exception("Error, could not update asset in EZOfficeInventory: " + str(e))
+
+    if response.status_code != 200:
+        print(
+            f"Error {response.status_code}, could not update asset in EZOfficeInventory: ",
+            response.content,
+        )
+        raise Exception(
+            f"Error {response.status_code}, could not update asset in EZOfficeInventory: "
+            + str(response.content)
+        )
+
+    return response.json()
+
+
+@Decorators.check_env_vars
+def delete_asset(asset_id: int) -> dict:
+    """
+    Delete an asset
+    https://ezo.io/ezofficeinventory/developers/#api-delete-asset
+    """
+
+    url = os.environ["EZO_BASE_URL"] + "assets/" + str(asset_id) + ".api"
+
+    try:
+        response = requests.delete(
+            url,
+            headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+            timeout=10,
+        )
+    except Exception as e:
+        print("Error, could not delete asset in EZOfficeInventory: ", e)
+        raise Exception("Error, could not delete asset in EZOfficeInventory: " + str(e))
+
+    if response.status_code != 200:
+        print(
+            f"Error {response.status_code}, could not delete asset in EZOfficeInventory: ",
+            response.content,
+        )
+        raise Exception(
+            f"Error {response.status_code}, could not delete asset in EZOfficeInventory: "
+            + str(response.content)
+        )
+
+    return response.json()
+
+
+@Decorators.check_env_vars
+def checkin_asset(asset_id: int, checkin: dict) -> dict:
+    """
+    Check in an asset to a location
+    https://ezo.io/ezofficeinventory/developers/#api-checkin-asset
+    """
+
+    # Required fields
+    if "checkin_values[location_id]" not in checkin:
+        raise ValueError("checkin must have 'checkin[location_id]' key")
+
+    # Remove any keys that are not valid
+    valid_keys = [
+        "checkin_values[location_id]",
+        "checkin_values[comments]",
+    ]
+
+    checkin = {
+        k: v
+        for k, v in checkin.items()
+        if k in valid_keys or k.startswith("checkin_values[c_attr_vals]")
+    }
+
+    url = os.environ["EZO_BASE_URL"] + "assets/" + str(asset_id) + "/checkin.api"
+
+    try:
+        response = requests.put(
+            url,
+            headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+            data=checkin,
+            timeout=10,
+        )
+    except Exception as e:
+        print("Error, could not checkin asset in EZOfficeInventory: ", e)
+        raise Exception(
+            "Error, could not checkin asset in EZOfficeInventory: " + str(e)
+        )
+
+    if response.status_code != 200:
+        print(
+            f"Error {response.status_code}, could not checkin asset in EZOfficeInventory: ",
+            response.content,
+        )
+        raise Exception(
+            f"Error {response.status_code}, could not checkin asset in EZOfficeInventory: "
+            + str(response.content)
+        )
+
+    return response.json()
+
+
+@Decorators.check_env_vars
+def checkout_asset(asset_id: int, user_id: int, checkout: dict) -> dict:
+    """
+    Check out an asset to a member
+    https://ezo.io/ezofficeinventory/developers/#api-checkout-asset
+
+    Note: If user is inactive, checkout will return a 200 status code but the
+    asset will not be checked out. Response will contain a message.
+    """
+
+    # Remove any keys that are not valid
+    valid_keys = [
+        "checkout_values[location_id]",
+        "checkout_values[comments]",
+        "till",
+        "till_time",
+        "checkout_values[override_conflicting_reservations]",
+        "checkout_values[override_my_conflicting_reservations]",
+    ]
+
+    checkout = {
+        k: v
+        for k, v in checkout.items()
+        if k in valid_keys or k.startswith("checkout_values[c_attr_vals]")
+    }
+
+    url = os.environ["EZO_BASE_URL"] + "assets/" + str(asset_id) + "/checkout.api"
+
+    try:
+        response = requests.put(
+            url,
+            headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+            params={"user_id": user_id},
+            data=checkout,
+            timeout=10,
+        )
+    except Exception as e:
+        print("Error, could not checkout asset in EZOfficeInventory: ", e)
+        raise Exception(
+            "Error, could not checkout asset in EZOfficeInventory: " + str(e)
+        )
+
+    if response.status_code != 200:
+        print(
+            f"Error {response.status_code}, could not checkout asset in EZOfficeInventory: ",
+            response.content,
+        )
+        raise Exception(
+            f"Error {response.status_code}, could not checkout asset in EZOfficeInventory: "
+            + str(response.content)
+        )
+
+    return response.json()
+
+
+@Decorators.check_env_vars
+def get_asset_history(asset_id: int) -> list[dict]:
+    """
+    Get asset history
+    https://ezo.io/ezofficeinventory/developers/#api-checkin-out-history
+    """
+
+    url = (
+        os.environ["EZO_BASE_URL"] + "assets/" + str(asset_id) + "/history_paginate.api"
+    )
+
+    page = 1
+    all_history = []
+
+    while True:
+        try:
+            response = requests.get(
+                url,
+                headers={"Authorization": "Bearer " + os.environ["EZO_TOKEN"]},
+                params={"page": page},
+                timeout=10,
+            )
+        except Exception as e:
+            print("Error, could not get asset history from EZOfficeInventory: ", e)
+            raise Exception(
+                "Error, could not get asset history from EZOfficeInventory: " + str(e)
+            )
+
+        if response.status_code != 200:
+            print(
+                f"Error {response.status_code}, could not get asset history from EZOfficeInventory: ",
+                response.content,
+            )
+            break
+
+        data = response.json()
+
+        if "history" not in data:
+            print(
+                f"Error, could not get asset history from EZOfficeInventory: ",
+                response.content,
+            )
+            raise Exception(
+                f"Error, could not get asset history from EZOfficeInventory: "
+                + str(response.content)
+            )
+
+        all_history.extend(data["history"])
+
+        if "total_pages" not in data:
+            print("Error, could not get total_pages from EZOfficeInventory: ", data)
+            break
+
+        if page >= data["total_pages"]:
+            break
+
+        page += 1
+
+    return all_history

ezoff-0.1.0/ezoff/auth.py

@@ -0,0 +1,28 @@
+"""
+Handles any authentication-realted functionality.
+Largely just checking if the required environment variables are set.
+"""
+
+import os
+
+
+class Decorators:
+
+    @staticmethod
+    def check_env_vars(decorated):
+        """
+        Decorator to check if the required environment variables are set
+        """
+
+        def wrapper(*args, **kwargs):
+            """
+            Wrapper function
+            """
+            if "EZO_BASE_URL" not in os.environ:
+                raise Exception("EZO_BASE_URL not found in environment variables.")
+            if "EZO_TOKEN" not in os.environ:
+                raise Exception("EZO_TOKEN not found in environment variables.")
+            return decorated(*args, **kwargs)
+
+        wrapper.__name__ = decorated.__name__
+        return wrapper

ezoff-0.1.0/ezoff/ezoff.py

@@ -0,0 +1,9 @@
+"""
+Module for interacting with the EZOffice Inventory API
+"""
+
+from .assets import *
+from .groups import *
+from .locations import *
+from .members import *
+from .workorders import *