opengamedata-api-utils 0.0.1__tar.gz

opengamedata_api_utils-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 opengamedata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

opengamedata_api_utils-0.0.1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.1
+Name: opengamedata-api-utils
+Version: 0.0.1
+Summary: Package of utilities for server-side scripts in OpenGameData.
+Author: Ryan Wilkinson, Glenn Palmer, Daus Husaini
+Author-email: Luke Swanson <superscription58@gmail.com>
+Project-URL: Homepage, https://github.com/opengamedata/opengamedata-api-utils
+Project-URL: Bug Tracker, https://github.com/opengamedata/opengamedata-api-utils/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask==2.3.3
+Requires-Dist: flask-restful==0.3.10
+Requires-Dist: requests==2.32.*
+Requires-Dist: opengamedata-common>=2.0.0b6
+
+# opengamedata-api-utils
+
+Repository for utility server-side script and classes used by OpenGameData APIs.
+
+## Contents
+
+### Python Package
+
+The `utils` repository contains a package that can be installed from `pip`, and places its classes under the `ogd.apis` namespace.
+The available modules include:
+
+* `HelloAPI.py` : Class for creating a "Hello, World" API to aid in testing deploys of other APIs.
+* `schemas` : Contains a base class for server config schemas to handle version and debug-level config items
+* `utils` : Contains helper classes for API requests and responses, as well as general-purpose parsing and setup functions.
+
+### Data Store Utilities
+
+The `store` directory contains a script for reindexing a folder of OGD datasets after new datasets have been added.
+This index is used by the FileAPI to check what datasets are available on the server.
+
+## Getting Started
+
+### Hello World of Flask
+
+Steps to run:
+
+1. Check out latest `opengamedata-server`.
+2. Run `pip install -r requirements.txt` to ensure you've got flask.
+3. Run `flask run`.
+4. Open localhost:5000 or localhost:5000/hello to see some really basic text output from the Flask server.
+
+If Flask doesn't run, it's possible you'd need to first export FLASK_APP as an environment variable, set to "wsgi" (so in Bash, export FLASK_APP=wsgi).
+However, the script is named wsgi.py specifically because Flask is supposed to auto-detect it. So if this issue ever did come up, please ping Luke so he can look into it.
+
+## Testing in VS Code
+
+Be sure to add the following to `.vscode/settings.json` in your local checkout:
+
+```json
+   "python.testing.unittestEnabled": true,
+   "python.testing.unittestArgs": [
+      "-v",
+      "-s",
+      "./tests/cases",
+      "-t",
+      "./",
+      "-p",
+      "t_*.py"
+   ],
+```

opengamedata_api_utils-0.0.1/README.md

@@ -0,0 +1,50 @@
+# opengamedata-api-utils
+
+Repository for utility server-side script and classes used by OpenGameData APIs.
+
+## Contents
+
+### Python Package
+
+The `utils` repository contains a package that can be installed from `pip`, and places its classes under the `ogd.apis` namespace.
+The available modules include:
+
+* `HelloAPI.py` : Class for creating a "Hello, World" API to aid in testing deploys of other APIs.
+* `schemas` : Contains a base class for server config schemas to handle version and debug-level config items
+* `utils` : Contains helper classes for API requests and responses, as well as general-purpose parsing and setup functions.
+
+### Data Store Utilities
+
+The `store` directory contains a script for reindexing a folder of OGD datasets after new datasets have been added.
+This index is used by the FileAPI to check what datasets are available on the server.
+
+## Getting Started
+
+### Hello World of Flask
+
+Steps to run:
+
+1. Check out latest `opengamedata-server`.
+2. Run `pip install -r requirements.txt` to ensure you've got flask.
+3. Run `flask run`.
+4. Open localhost:5000 or localhost:5000/hello to see some really basic text output from the Flask server.
+
+If Flask doesn't run, it's possible you'd need to first export FLASK_APP as an environment variable, set to "wsgi" (so in Bash, export FLASK_APP=wsgi).
+However, the script is named wsgi.py specifically because Flask is supposed to auto-detect it. So if this issue ever did come up, please ping Luke so he can look into it.
+
+## Testing in VS Code
+
+Be sure to add the following to `.vscode/settings.json` in your local checkout:
+
+```json
+   "python.testing.unittestEnabled": true,
+   "python.testing.unittestArgs": [
+      "-v",
+      "-s",
+      "./tests/cases",
+      "-t",
+      "./",
+      "-p",
+      "t_*.py"
+   ],
+```

opengamedata_api_utils-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = [
+    "build == 1.2.*",
+    "setuptools == 74.1.*",
+    "setuptools-git-versioning == 2.0.*",
+    "twine == 5.1.*",
+    "wheel == 0.44.*"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools-git-versioning]
+enabled = true
+
+[tool.setuptools.dynamic]
+dependencies = {file = ["requirements.txt"]}
+
+[project]
+name = "opengamedata-api-utils"
+dynamic = ["version", "dependencies"]
+authors = [
+   { name="Luke Swanson", email="superscription58@gmail.com" },
+   { name="Ryan Wilkinson" },
+   { name="Glenn Palmer" },
+   { name="Daus Husaini" }
+]
+description = "Package of utilities for server-side scripts in OpenGameData."
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/opengamedata/opengamedata-api-utils"
+"Bug Tracker" = "https://github.com/opengamedata/opengamedata-api-utils/issues"

opengamedata_api_utils-0.0.1/requirements.txt

@@ -0,0 +1,5 @@
+flask==2.3.3
+flask-restful==0.3.10
+requests==2.32.*
+# ogd packages
+opengamedata-common>=2.0.0b6

opengamedata_api_utils-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opengamedata_api_utils-0.0.1/src/ogd/apis/HelloAPI.py

@@ -0,0 +1,48 @@
+"""
+HelloAPI
+
+Contains the HelloAPI class, which we register to all API apps as a way to test that the app is active.
+"""
+
+# import libraries
+from enum import StrEnum
+from typing import Optional
+
+# import 3rd-party libraries
+from flask import Flask
+from flask_restful import Resource, Api
+
+# import OGD libraries
+
+# import locals
+from ogd.apis.resources.Hello import Hello
+from ogd.apis.resources.ParamHello import ParamHello
+from ogd.apis.configs.ServerConfig import ServerConfig
+from ogd.apis.models.enums.ResponseStatus import ResponseStatus
+from ogd.apis.models.enums.RESTType import RESTType
+from ogd.apis.models.APIResponse import APIResponse
+
+class HelloAPI:
+    class ENDPOINTS(StrEnum):
+        HELLO = 'hello'
+        VERSION = 'version'
+
+    @staticmethod
+    def register(app:Flask, server_config:ServerConfig, root_endpoint:Optional[ENDPOINTS | str]=None):
+        api = Api(app)
+        urls = ['/hello'] + (['/'] if root_endpoint == HelloAPI.ENDPOINTS.HELLO else [])
+        api.add_resource(Hello, *urls)
+        api.add_resource(ParamHello, '/p_hello/<name>')
+        urls = ['/version'] + (['/'] if root_endpoint == HelloAPI.ENDPOINTS.VERSION else [])
+        api.add_resource(HelloAPI.Version, *urls)
+
+        HelloAPI.server_config = server_config
+
+    class Version(Resource):
+        def get(self):
+            ret_val = APIResponse(
+                req_type = RESTType.GET,
+                val      = { "version" : str(HelloAPI.server_config.Version) },
+                msg      = "Successfully retrieved API version.",
+                status   = ResponseStatus.OK)
+            return ret_val.AsDict

opengamedata_api_utils-0.0.1/src/ogd/apis/configs/ServerConfig.py

@@ -0,0 +1,137 @@
+"""
+ServerConfig
+
+Contains a Config class for managing config data for server configurations.
+"""
+
+# import standard libraries
+import logging
+from typing import Dict, Final, Optional, Self
+
+# import 3rd-party libraries
+
+# import OGD libraries
+from ogd.common.configs.Config import Config
+from ogd.common.models.SemanticVersion import SemanticVersion
+from ogd.common.utils.typing import JSONMap, Map
+from ogd.common.utils.Logger import Logger
+
+# import local files
+
+class ServerConfig(Config):
+    _DEFAULT_DEBUG_LEVEL : Final[int] = logging.INFO
+    _DEFAULT_VERSION     : Final[str] = "UNKNOWN VERSION"
+
+    # *** BUILT-INS & PROPERTIES ***
+
+    def __init__(self, name:str,
+                 debug_level:Optional[int], version:Optional[SemanticVersion],
+                 other_elements:Optional[Map]=None):
+
+        unparsed_elements : Map = other_elements or {}
+
+        self._dbg_level : int
+        self._version   : SemanticVersion
+
+        self._version   = version     if version     is not None else self._parseVersion(unparsed_elements=unparsed_elements, schema_name=name)
+        self._dbg_level = debug_level if debug_level is not None else self._parseDebugLevel(unparsed_elements=unparsed_elements, schema_name=name)
+
+        super().__init__(name=name, other_elements=other_elements)
+
+    @property
+    def DebugLevel(self) -> int:
+        return self._dbg_level
+
+    @property
+    def Version(self) -> SemanticVersion:
+        return self._version
+
+    # *** IMPLEMENT ABSTRACT FUNCTIONS ***
+
+    @property
+    def AsMarkdown(self) -> str:
+        ret_val : str
+
+        ret_val = f"{self.Name}"
+        return ret_val
+
+    @property
+    def AsDict(self) -> JSONMap:
+        return {
+            "API_VERSION": str(self.Version),
+            "DEBUG_LEVEL": self.DebugLevel
+        }
+
+    @classmethod
+    def Default(cls):
+        return ServerConfig(
+            name="DefaultServerConfig",
+            debug_level=ServerConfig._DEFAULT_DEBUG_LEVEL,
+            version=SemanticVersion.FromString("0.0.0-Testing"),
+            other_elements={}
+        )
+
+    @classmethod
+    def _fromDict(cls, name:str, unparsed_elements:Map,
+                  key_overrides:Optional[Dict[str, str]]=None,
+                  default_override:Optional[Self]=None):
+        return ServerConfig(name=name, debug_level=None, version=None, other_elements=unparsed_elements)
+
+    @staticmethod
+    def _parseDebugLevel(unparsed_elements:Map, schema_name:Optional[str]=None) -> int:
+        ret_val : int
+
+        raw_level : str = ServerConfig.ParseElement(
+            unparsed_elements=unparsed_elements,
+            valid_keys=["DEBUG_LEVEL"],
+            to_type=[int, str],
+            default_value=ServerConfig._DEFAULT_DEBUG_LEVEL,
+            remove_target=True,
+            schema_name=schema_name
+        )
+        if isinstance(raw_level, int):
+            if raw_level in {logging.ERROR, logging.WARN, logging.INFO, logging.DEBUG}:
+                ret_val = raw_level
+            else:
+                ret_val = ServerConfig._DEFAULT_DEBUG_LEVEL
+                Logger.Log(f"Debug level had a value of {raw_level}, but this does not correspond to a valid logging level, defaulting to {ret_val}.", logging.WARNING)
+        elif isinstance(raw_level, str):
+            match raw_level.upper():
+                case "ERROR":
+                    ret_val = logging.ERROR
+                case "WARNING" | "WARN":
+                    ret_val = logging.WARN
+                case "INFO":
+                    ret_val = logging.INFO
+                case "DEBUG":
+                    ret_val = logging.DEBUG
+                case _:
+                    ret_val = ServerConfig._DEFAULT_DEBUG_LEVEL
+                    Logger.Log(f"Config debug level had unexpected value {raw_level}, defaulting to {ret_val}.", logging.WARNING)
+        else:
+            ret_val = ServerConfig._DEFAULT_DEBUG_LEVEL
+            Logger.Log(f"Config debug level was unexpected type {type(raw_level)}, defaulting to {ret_val}.", logging.WARNING)
+
+        return ret_val
+
+    @staticmethod
+    def _parseVersion(unparsed_elements:Map, schema_name:Optional[str]=None) -> SemanticVersion:
+        ret_val : SemanticVersion
+
+        raw_version = ServerConfig.ParseElement(
+            unparsed_elements=unparsed_elements,
+            valid_keys=["API_VERSION"],
+            to_type=[int, str],
+            default_value=ServerConfig._DEFAULT_VERSION,
+            remove_target=True,
+            schema_name=schema_name
+        )
+        if isinstance(raw_version, int):
+            ret_val = SemanticVersion(major=raw_version)
+        elif isinstance(raw_version, str):
+            ret_val = SemanticVersion.FromString(semver=raw_version)
+        else:
+            ret_val = SemanticVersion.FromString(str(raw_version))
+            Logger.Log(f"Config version was unexpected type {type(raw_version)}, defaulting to SemanticVersion(str(version))={ret_val}.", logging.WARN)
+
+        return ret_val

opengamedata_api_utils-0.0.1/src/ogd/apis/models/APIRequest.py

@@ -0,0 +1,101 @@
+import logging
+from typing import Any, Dict, Optional
+
+import requests
+from flask import current_app
+
+from ogd.apis.models.enums.RESTType import RESTType
+from ogd.apis.models.enums.ResponseStatus import ResponseStatus
+from ogd.apis.models.APIResponse import APIResponse
+
+class APIRequest:
+    def __init__(self, url:str, request_type:str | RESTType, params:Optional[Dict[str, Any]]=None, body:Optional[Dict[str, Any]]=None, timeout:int=1):
+        """Utility function to make it easier to send requests to a remote server during unit testing.
+
+        This function does some basic sanity checking of the target URL,
+        maps the request type to the appropriate `requests` function call,
+        and performs basic error handling to notify what error occurred.
+
+        :param url: The target URL for the web request
+        :type url: str
+        :param request: Whether to perform a "GET", "POST", or "PUT" request
+        :type request: str
+        :param params: A mapping of request parameter names to values. Defaults to {}
+        :type params: Dict[str, Any], optional
+        :param body: The body of the request to send. Defaults to None
+        :type body: Dict[str, Any], optional
+        :param logger: A logger to use for debug/error outputs. Defaults to None
+        :type logger: logging.Logger, optional
+        :raises err: Currently, any exceptions that occur during the request will be raised up.
+            If verbose logging is on, a simple debug message indicating the request type and URL is printed first.
+        :return: The `Response` object from the request, or None if an error occurred.
+        :rtype: requests.Response
+        """
+        params = params or {}
+
+        self._request_type : RESTType
+
+        if not (url.startswith("http://") or url.startswith("https://")):
+            url = f"https://{url}"
+        match request_type:
+            case RESTType():
+                self._request_type = request_type
+            case str():
+                try:
+                    self._request_type = RESTType[request_type.upper()]
+                except KeyError:
+                    current_app.logger.warning(f"Bad request type {request_type}, defaulting to GET")
+                    self._request_type = RESTType.GET
+            case _:
+                raise TypeError(f"request_type for APIRequest was invalid type {type(request_type)}")
+
+        self._url = url
+        self._params = params
+        self._body = body
+        self._timeout = timeout
+
+    def __str__(self) -> str:
+        return f"Request: {self._request_type} {self._url}"
+        
+    def Execute(self, logger:Optional[logging.Logger]=None, retry:int=0) -> APIResponse:
+        ret_val : APIResponse
+
+        if logger is None and current_app:
+            logger = current_app.logger
+
+        response : requests.Response
+        try:
+            match (self._request_type):
+                case RESTType.GET:
+                    response = requests.get( self._url, params=self._params, timeout=self._timeout)
+                case RESTType.POST:
+                    response = requests.post(self._url, params=self._params, data=self._body, timeout=self._timeout)
+                case RESTType.PUT:
+                    response = requests.put( self._url, params=self._params, data=self._body, timeout=self._timeout)
+                case _:
+                    if logger:
+                        logger.warning(f"Bad request type {self._request_type}, defaulting to GET")
+                    response = requests.get(self._url, params=self._params, timeout=self._timeout)
+        except requests.exceptions.ReadTimeout:
+            if retry < 5:
+                if logger:
+                    logger.error(f"Timeout error executing {self}, trying again...")
+                return self.Execute(logger=logger, retry=retry+1)
+            else:
+                if logger:
+                    logger.error(f"Timeout error executing {self}.")
+                return APIResponse(req_type=self._request_type, val=None, msg="Could not retrieve results, server timed out!", status=ResponseStatus.GATEWAY_TIMEOUT)
+        except Exception as err:
+            if logger:
+                logger.error(f"Error on {self._request_type} request to {self._url} : {err}")
+            return APIResponse(req_type=self._request_type, val=None, msg="Could not retrieve results, encountered an unexpected error while executing request!", status=ResponseStatus.INTERNAL_ERR)
+        else:
+            ret_val = APIResponse.FromResponse(response)
+            if logger:
+                out = logger.debug if ret_val.Status == ResponseStatus.OK else logger.warning
+                out(f"Request sent to:        {self._url}, with params {self._params}")
+                out(f"Response received from: {self._url}")
+                out(f"   Status: {ret_val.Status}")
+                out(f"   Msg:    {ret_val.Message}")
+                out(f"   Value:  {ret_val.Value}")
+        return ret_val

opengamedata_api_utils-0.0.1/src/ogd/apis/models/APIResponse.py

@@ -0,0 +1,173 @@
+"""
+APIResponse
+
+Contains class for representing a response from an OGD API,
+as well as utility enums used by the APIResponse class.
+"""
+
+# import standard libraries
+import json
+import logging
+from typing import Any, Dict, Optional
+
+# import 3rd-party libraries
+import requests
+from flask import Response
+
+# import OGD libraries
+from ogd.common.utils.typing import Map
+from ogd.common.utils.Logger import Logger
+
+# Import local files
+from ogd.apis.models.enums.RESTType import RESTType
+from ogd.apis.models.enums.ResponseStatus import ResponseStatus
+
+class APIResponse:
+    def __init__(self, req_type:Optional[RESTType | str], val:Optional[Map], msg:str, status:ResponseStatus):
+        self._type   : Optional[RESTType]
+        self._val    : Optional[Map]
+
+        match req_type:
+            case RESTType():
+                self._type = req_type
+            case str():
+                self._type = RESTType[req_type]
+            case _:
+                self._type = None
+        match val:
+            case dict() | None:
+                self._val = val
+            case _:
+                try:
+                    self._val = json.loads(str(val))
+                except json.decoder.JSONDecodeError as err:
+                    abbreviated_val = f"{str(val)[:20]}..." if len(str(val)) > 20 else str(val)
+                    _msg = f"API response 'value' field contained value '{abbreviated_val}' with invalid type {type(val)}, which could not be converted to a dictionary. Attempting to do so resulted in error:\n{err}\nThe value field will be left blank."
+                    Logger.Log(_msg, logging.ERROR)
+                    self._val = None
+        self._msg    : str                = msg
+        self._status : ResponseStatus     = status
+
+    def __str__(self):
+        return f"{str(self.Type)} request: {self.Status}\n{self.Message}\nValues: {self.Value}"
+
+    @staticmethod
+    def Default(req_type:RESTType):
+        return APIResponse(
+            req_type=req_type,
+            val=None,
+            msg="",
+            status=ResponseStatus.NONE
+        )
+
+    @staticmethod
+    def FromResponse(result:requests.Response) -> "APIResponse":
+        ret_val : APIResponse
+
+        try:
+            raw = result.json()
+            ret_val = APIResponse(req_type=raw.get("type"), val=raw.get("val"), msg=raw.get("msg"), status=ResponseStatus(result.status_code))
+        except requests.exceptions.JSONDecodeError:
+            ret_val = APIResponse(req_type=None, val=None, msg=result.text, status=ResponseStatus(result.status_code))
+
+        return ret_val
+    
+    @staticmethod
+    def FromDict(all_elements:Dict[str, Any], status:Optional[ResponseStatus]=None) -> Optional["APIResponse"]:
+        ret_val : Optional["APIResponse"] = None
+
+        _type_raw   = all_elements.get("type", None)
+        _val_raw    = all_elements.get("val",  None)
+        _msg        = all_elements.get("msg", "NOT FOUND")
+        _status_raw = all_elements.get("status", None)
+        try:
+            _type   = RESTType[str(_type_raw).upper()] if _type_raw else None
+            _val    = _val_raw if isinstance(_val_raw, dict) else json.loads(str(_val_raw)) if _val_raw is not None else None
+            _status = ResponseStatus[str(_status_raw).upper()] if _status_raw else (status or ResponseStatus.NONE)
+        except KeyError:
+            pass
+        else:
+            ret_val = APIResponse(req_type=_type, val=_val, msg=_msg, status=_status)
+        return ret_val
+
+    @property
+    def Type(self) -> Optional[RESTType]:
+        """Property for the type of REST request
+
+        :return: A RESTType representing the type of REST request
+        :rtype: _type_
+        """
+        return self._type
+
+    @property
+    def Value(self) -> Optional[Map]:
+        """Property for the value of the request result.
+
+        :return: Some value, of any type, returned from the request.
+        :rtype: Any
+        """
+        return self._val
+    @Value.setter
+    def Value(self, new_val:Optional[Map]):
+        self._val = new_val
+
+
+    @property
+    def Message(self) -> str:
+        """Property for the message associated with a request result.
+
+        :return: A string message giving details on the result of the request.
+        :rtype: str
+        """
+        return self._msg
+    @Message.setter
+    def Message(self, new_msg:str):
+        self._msg = new_msg
+
+    @property
+    def Status(self) -> ResponseStatus:
+        """Property for the status of the request.
+
+        :return: A ResponseStatus indicating whether request is/was successful, incomplete, failed, etc.
+        :rtype: ResponseStatus
+        """
+        return self._status
+    @property
+    def OK(self) -> bool:
+        """Property indicating whether the APIResponse was successful or not.
+
+        Technically, this includes both a true "OK" response and any other 200-range response.
+
+        :return: True if the APIResponse status is in the 200 range, otherwise False.
+        :rtype: bool
+        """
+        return self.Status in ResponseStatus.SuccessStatuses()
+
+    @property
+    def AsDict(self):
+        return {
+            "type"   : str(self._type),
+            "val"    : self._val,
+            "msg"    : self._msg,
+        }
+
+    @property
+    def AsJSON(self):
+        return json.dumps(self.AsDict)
+
+    @property
+    def AsFlaskResponse(self) -> Response:
+        return Response(response=self.AsJSON, status=self.Status.value, mimetype='application/json')
+
+    def RequestErrored(self, msg:str, status:Optional[ResponseStatus]=None):
+        self._status = status if status is not None and status in ResponseStatus.ClientErrors() else ResponseStatus.BAD_REQUEST
+        self.Message = f"ERROR: {msg}"
+
+    def ServerErrored(self, msg:str, status:Optional[ResponseStatus]=None):
+        self._status = status if status is not None and status in ResponseStatus.ServerErrors() else ResponseStatus.INTERNAL_ERR
+        self.Message = f"SERVER ERROR: {msg}"
+
+    def RequestSucceeded(self, msg:str, val:Optional[Map]):
+        self._status = ResponseStatus.OK
+        self.Message = f"SUCCESS: {msg}"
+        self.Value   = val

opengamedata_api_utils-0.0.1/src/ogd/apis/models/enums/RESTType.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+class RESTType(StrEnum):
+    """Simple enumerated type to track type of a REST request.
+    """
+    GET  = "GET"
+    POST = "POST"
+    PUT  = "PUT"

opengamedata_api_utils-0.0.1/src/ogd/apis/models/enums/ResponseStatus.py

@@ -0,0 +1,117 @@
+from enum import IntEnum
+from typing import Set
+
+class ResponseStatus(IntEnum):
+    """Enumerated type to track the status of an API request result.
+    """
+    NONE          =   1
+    CONTINUE      = 100
+    OK            = 200
+    MULTI_CHOICES = 300
+    BAD_REQUEST   = 400
+    INTERNAL_ERR  = 500
+
+    # 100s
+    SWITCHING_PROTOCOLS = 101
+    PROCESSING          = 102
+    EARLY_HINTS         = 103
+
+    # 200s
+    CREATED           = 201
+    ACCEPTED          = 202
+    NON_AUTHORITATIVE = 203
+    NO_CONTENT        = 204
+    RESET             = 205
+    PARTIAL           = 206
+    MULTI_STATUS      = 207
+    ALREADY_REPORTED  = 208
+    IM_USED           = 226
+
+    # 300s
+    MOVED           = 301
+    FOUND           = 302
+    SEE_OTHER       = 303
+    NOT_MODIFIED    = 304
+    TEMPORARY_REDIR = 307
+    PERMANENT_REDIR = 308
+
+    # 400s
+    UNAUTHORIZED        = 401
+    PAYMENT_REQUIRED    = 402
+    FORBIDDEN           = 403
+    NOT_FOUND           = 404
+    METHOD_NOT_ALLOWED  = 405
+    NOT_ACCEPTABLE      = 406
+    PROXY_AUTH_REQUIRED = 407
+    REQUEST_TIMEOUT     = 408
+    CONFLICT            = 409
+    GONE                = 410
+    LENGTH_REQUIRED     = 411
+    PRECONDITION_FAILED = 412
+    CONTENT_TOO_LARGE   = 413
+    URI_TOO_LONG        = 414
+    UNSUPPORTED_MEDIA   = 415
+    RANGE_INVALID       = 416
+    EXPECTATION_FAIL    = 417
+    IM_A_TEAPOT         = 418
+    MISDIRECTED         = 421
+    TOO_EARLY           = 425
+    UPGRADE_REQUIRED    = 426
+    PRECONDITION_REQUIRED = 428
+    TOO_MANY_REQUESTS   = 429
+    HEADERS_TOO_LARGE   = 431
+    ILLEGAL             = 451
+
+    # 400s WebDAV
+    UNPROCESSABLE     = 422
+    LOCKED            = 423
+    FAILED_DEPENDENCY = 424
+
+    # 500s
+    NOT_IMPLEMENTED          = 501
+    BAD_GATEWAY              = 502
+    UNAVAILABLE              = 503
+    GATEWAY_TIMEOUT          = 504
+    UNSUPPORTED_HTTP_VERSION = 505
+    VARIANT_NEGOTIATES       = 506
+    NOT_EXTENDED             = 510
+    NETWORK_AUTH_REQUIRED    = 511
+
+    # 500s WebDAV
+    INSUFFICIENT_STORAGE = 507
+    LOOP_DETECTED        = 508
+
+    @staticmethod
+    def SuccessStatuses() -> Set["ResponseStatus"]:
+        """Gets the set of valid 400-level "client" error responses.
+
+        :return: The set of valid 400-level "client" error responses.
+        :rtype: Set[ResponseStatus]
+        """
+        return {status for status in set(ResponseStatus) if status in range(200, 300)}
+
+    @staticmethod
+    def ClientErrors() -> Set["ResponseStatus"]:
+        """Gets the set of valid 400-level "client" error responses.
+
+        :return: The set of valid 400-level "client" error responses.
+        :rtype: Set[ResponseStatus]
+        """
+        return {status for status in set(ResponseStatus) if status in range(400, 500)}
+
+    @staticmethod
+    def ServerErrors() -> Set["ResponseStatus"]:
+        """Gets the set of valid 500-level "server" error responses.
+
+        :return: The set of valid 500-level "server" error responses.
+        :rtype: Set[ResponseStatus]
+        """
+        return {status for status in set(ResponseStatus) if status in range(500, 600)}
+
+    def __str__(self):
+        """Stringify function for ResponseStatus objects.
+
+        :return: Simple string version of the name of a ResponseStatus
+        :rtype: _type_
+        """
+        return self.name

opengamedata_api_utils-0.0.1/src/ogd/apis/resources/Hello.py

@@ -0,0 +1,29 @@
+# import 3rd-party libraries
+from flask_restful import Resource
+
+from ogd.apis.models.APIResponse import APIResponse, RESTType, ResponseStatus
+
+class Hello(Resource):
+    def get(self):
+        ret_val = APIResponse(
+            req_type = RESTType.GET,
+            val      = None,
+            msg      = "Hello! You GETted successfully!",
+            status   = ResponseStatus.OK)
+        return ret_val.AsDict
+
+    def post(self):
+        ret_val = APIResponse(
+            req_type = RESTType.POST,
+            val      = None,
+            msg      = "Hello! You POSTed successfully!",
+            status   = ResponseStatus.OK)
+        return ret_val.AsDict
+
+    def put(self):
+        ret_val = APIResponse(
+            req_type = RESTType.PUT,
+            val      = None,
+            msg      = "Hello! You PUTted successfully!",
+            status   = ResponseStatus.OK)
+        return ret_val.AsDict

opengamedata_api_utils-0.0.1/src/ogd/apis/resources/ParamHello.py

@@ -0,0 +1,29 @@
+# import 3rd-party libraries
+from flask_restful import Resource
+
+from ogd.apis.models.APIResponse import APIResponse, RESTType, ResponseStatus
+
+class ParamHello(Resource):
+    def get(self, name):
+        ret_val = APIResponse(
+            req_type = RESTType.GET,
+            val      = None,
+            msg      = f"Hello {name}! You GETted successfully!",
+            status   = ResponseStatus.OK)
+        return ret_val.AsDict
+
+    def post(self, name):
+        ret_val = APIResponse(
+            req_type = RESTType.POST,
+            val      = None,
+            msg      = f"Hello {name}! You POSTed successfully!",
+            status   = ResponseStatus.OK)
+        return ret_val.AsDict
+
+    def put(self, name):
+        ret_val = APIResponse(
+            req_type = RESTType.PUT,
+            val      = None,
+            msg      = f"Hello {name}! You PUTted successfully!",
+            status   = ResponseStatus.OK)
+        return ret_val.AsDict

opengamedata_api_utils-0.0.1/src/ogd/apis/utils/APIUtils.py

@@ -0,0 +1,128 @@
+"""
+APIUtils
+
+Contains general utility functions for common  tasks when setting up our flask/flask-restful API functions.
+In particular, has functions to assist in parsing certain kinds of data, and for generating OGD-core objects.
+"""
+
+# import standard libraries
+import json
+from json.decoder import JSONDecodeError
+from logging import Logger
+from typing import Any, List, Optional
+from urllib import parse
+
+def parse_list(list_str:str, logger:Optional[Logger]=None) -> Optional[List[Any]]:
+    """Simple utility to parse a string containing a bracketed list into a Python list.
+    Returns None if the list was empty
+
+    :param list_str: _description_
+    :type list_str: str
+    :return: A list parsed from the input string, or None if the string list was invalid or empty.
+    :rtype: Union[List[Any], None]
+    """
+    ret_val : Optional[List[Any]] = None
+    try:
+        ret_val = json.loads(list_str)
+    except JSONDecodeError as e:
+        if logger:
+            logger.warning(f"Could not parse '{list_str}' as a list, format was not valid!\nGot Error {e}")
+    else:
+        if ret_val is not None and len(ret_val) == 0:
+            # If we had empty list, just treat as null.
+            ret_val = None
+    return ret_val
+
+def urljoin(base:str, url:str, ignore_base_file:bool=False, allow_fragments:bool=True):
+    """Custom variation of the `urllib.parse.urljoin` function provided by Python.
+
+    By default, this version allows filenames in the base path to remain in the joined path.
+
+    This is useful for working with Flask apps, particularly on Apache.
+    Specifically, unless you alias things in Apache, you'll have `app.py` or `app.wsgi` in the URL.
+    For a Flask API, then, you'll likely be joining a base URL like `"https://host.of.app/path/to/app.wsgi"` with an endpoint, call it `"endpoint"`.
+    Under `urllib.parse.urljoin`, you'll get `"https://host.of.app/path/to/endpoint"`.
+    With _this_ function, setting `ignore_base_file=False`, you'll get `"http://host.of.app/path/to/app.wsgi/endpoint"` as desired.
+
+    When `ignore_base_file=True`, this function directly falls back to use `urllib.parse.urljoin`.
+
+    :param base: The base URL, onto which the `url` parameter is joined.
+    :type base: str
+    :param url: The URL to be joined onto the given base URL.
+    :type url: str
+    :param ignore_base_file: Whether to ignore filenames in the base URL.  
+        When True, such filenames are removed from the joined URL.
+        For example, joining `https://host.of.app/path/to/app.wsgi` with `endpoint` would yield `https://host.of.app/path/to/endpoint`.  
+        When False, such filenames are included in the joined URL.
+    :type ignore_base_file: bool
+    :param allow_fragments: Whether to allow fragment parts in the URLs.  
+        This is only used when `ignore_base_file=True`, in which case this function falls back on `urllib.parse.urljoin` and `allow_fragments` is passed to that function call.
+    :type ignore_base_file: bool
+    """
+    if ignore_base_file:
+        return parse.urljoin(base=base, url=url, allow_fragments=allow_fragments)
+    else:
+        # Make sure we have a scheme
+        if not (base.startswith("http://") or base.startswith("https://")):
+            base = f"https://{base}"
+        # If base ends with a /, remove it so we don't double-up when joining
+        if base.endswith("/"):
+            base = base[:-1]
+        # If url starts with a /, remove it so we don't double-up when joining
+        if url.startswith("/"):
+            url = url[1:]
+        return f"{base}/{url}"
+
+# def gen_interface(game_id, core_config:ConfigSchema, logger:Optional[Logger]=None) -> Optional[Interface]:
+#     """Utility to set up an Interface object for use by the API, given a game_id.
+
+#     :param game_id: _description_
+#     :type game_id: _type_
+#     :return: _description_
+#     :rtype: _type_
+#     """
+#     ret_val = None
+    
+#     _game_source : DataTableConfig = core_config.GameSourceMap.get(game_id, DataTableConfig.Default())
+
+#     if _game_source.Source is not None:
+#         # set up interface and request
+#         match _game_source.Source.Type.upper():
+#             case "MYSQL":
+#                 ret_val = MySQLInterface(game_id, config=_game_source, fail_fast=False)
+#                 if logger:
+#                     logger.info(f"Using MySQLInterface for {game_id}")
+#             case "BIGQUERY":
+#                 if logger:
+#                     logger.info(f"Generating BigQueryInterface for {game_id}, from directory {os.getcwd()}...")
+#                 ret_val = BigQueryInterface(game_id=game_id, config=_game_source, fail_fast=False)
+#                 if logger:
+#                     logger.info("Done")
+#             case _:
+#                 ret_val = MySQLInterface(game_id, config=_game_source, fail_fast=False)
+#                 if logger:
+#                     logger.warning(f"Could not find a valid interface for {game_id}, defaulting to MySQL!")
+#     return ret_val
+
+# def gen_coding_interface(game_id) -> Optional[CodingInterface]:
+#     """Utility to set up an Interface object for use by the API, given a game_id.
+
+#     :param game_id: _description_
+#     :type game_id: _type_
+#     :return: _description_
+#     :rtype: _type_
+#     """
+#     ret_val = None
+
+#     _core_config = ConfigSchema(name="Core Config", all_elements=core_settings)
+#     _game_source : GameSourceSchema = _core_config.GameSourceMap.get(game_id, GameSourceSchema.EmptySchema())
+
+#     if _game_source.Source is not None:
+#         # set up interface and request
+#         if _game_source.Source.Type == "BigQuery":
+#             ret_val = BigQueryCodingInterface(game_id=game_id, config=_core_config)
+#             current_app.logger.info(f"Using BigQueryCodingInterface for {game_id}")
+#         else:
+#             ret_val = BigQueryCodingInterface(game_id=game_id, config=_core_config)
+#             current_app.logger.warning(f"Could not find a valid interface for {game_id}, defaulting to BigQuery!")
+#     return ret_val

opengamedata_api_utils-0.0.1/src/opengamedata_api_utils.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.1
+Name: opengamedata-api-utils
+Version: 0.0.1
+Summary: Package of utilities for server-side scripts in OpenGameData.
+Author: Ryan Wilkinson, Glenn Palmer, Daus Husaini
+Author-email: Luke Swanson <superscription58@gmail.com>
+Project-URL: Homepage, https://github.com/opengamedata/opengamedata-api-utils
+Project-URL: Bug Tracker, https://github.com/opengamedata/opengamedata-api-utils/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask==2.3.3
+Requires-Dist: flask-restful==0.3.10
+Requires-Dist: requests==2.32.*
+Requires-Dist: opengamedata-common>=2.0.0b6
+
+# opengamedata-api-utils
+
+Repository for utility server-side script and classes used by OpenGameData APIs.
+
+## Contents
+
+### Python Package
+
+The `utils` repository contains a package that can be installed from `pip`, and places its classes under the `ogd.apis` namespace.
+The available modules include:
+
+* `HelloAPI.py` : Class for creating a "Hello, World" API to aid in testing deploys of other APIs.
+* `schemas` : Contains a base class for server config schemas to handle version and debug-level config items
+* `utils` : Contains helper classes for API requests and responses, as well as general-purpose parsing and setup functions.
+
+### Data Store Utilities
+
+The `store` directory contains a script for reindexing a folder of OGD datasets after new datasets have been added.
+This index is used by the FileAPI to check what datasets are available on the server.
+
+## Getting Started
+
+### Hello World of Flask
+
+Steps to run:
+
+1. Check out latest `opengamedata-server`.
+2. Run `pip install -r requirements.txt` to ensure you've got flask.
+3. Run `flask run`.
+4. Open localhost:5000 or localhost:5000/hello to see some really basic text output from the Flask server.
+
+If Flask doesn't run, it's possible you'd need to first export FLASK_APP as an environment variable, set to "wsgi" (so in Bash, export FLASK_APP=wsgi).
+However, the script is named wsgi.py specifically because Flask is supposed to auto-detect it. So if this issue ever did come up, please ping Luke so he can look into it.
+
+## Testing in VS Code
+
+Be sure to add the following to `.vscode/settings.json` in your local checkout:
+
+```json
+   "python.testing.unittestEnabled": true,
+   "python.testing.unittestArgs": [
+      "-v",
+      "-s",
+      "./tests/cases",
+      "-t",
+      "./",
+      "-p",
+      "t_*.py"
+   ],
+```

opengamedata_api_utils-0.0.1/src/opengamedata_api_utils.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+requirements.txt
+src/ogd/apis/HelloAPI.py
+src/ogd/apis/__init__.py
+src/ogd/apis/configs/ServerConfig.py
+src/ogd/apis/configs/__init__.py
+src/ogd/apis/models/APIRequest.py
+src/ogd/apis/models/APIResponse.py
+src/ogd/apis/models/__init__.py
+src/ogd/apis/models/enums/RESTType.py
+src/ogd/apis/models/enums/ResponseStatus.py
+src/ogd/apis/models/enums/__init__.py
+src/ogd/apis/resources/Hello.py
+src/ogd/apis/resources/ParamHello.py
+src/ogd/apis/utils/APIUtils.py
+src/ogd/apis/utils/__init__.py
+src/opengamedata_api_utils.egg-info/PKG-INFO
+src/opengamedata_api_utils.egg-info/SOURCES.txt
+src/opengamedata_api_utils.egg-info/dependency_links.txt
+src/opengamedata_api_utils.egg-info/requires.txt
+src/opengamedata_api_utils.egg-info/top_level.txt

opengamedata_api_utils-0.0.1/src/opengamedata_api_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opengamedata_api_utils-0.0.1/src/opengamedata_api_utils.egg-info/requires.txt

@@ -0,0 +1,4 @@
+flask==2.3.3
+flask-restful==0.3.10
+requests==2.32.*
+opengamedata-common>=2.0.0b6

opengamedata_api_utils-0.0.1/src/opengamedata_api_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+ogd