clams-python 1.1.3__tar.gz → 1.1.5__tar.gz

{clams-python-1.1.3/clams_python.egg-info → clams-python-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clams-python
-Version: 1.1.3
+Version: 1.1.5
 Summary: A collection of APIs to develop CLAMS app for python
 Home-page: https://clams.ai
 Author: Brandeis Lab for Linguistics and Computation
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mmif-python==1.0.10
+Requires-Dist: mmif-python==1.0.11
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

clams-python-1.1.5/VERSION

@@ -0,0 +1 @@
+1.1.5

{clams-python-1.1.3 → clams-python-1.1.5}/clams/app/__init__.py

@@ -9,10 +9,10 @@ from urllib import parse as urlparser
 
 __all__ = ['ClamsApp']
 
-from typing import Union, Any, Optional
+from typing import Union, Any, Optional, Dict, List, Tuple
 
 from mmif import Mmif, Document, DocumentTypes, View
-from clams.appmetadata import AppMetadata
+from clams.appmetadata import AppMetadata, real_valued_primitives, python_type, map_param_kv_delimiter
 
 logging.basicConfig(
     level=logging.WARNING,
@@ -28,12 +28,14 @@ class ClamsApp(ABC):
     """
     # A set of "universal runtime parameters that can be used for both GET and POST anytime".
     # The behavioral changes based on these parameters must be implemented on the SDK level. 
+    # This needs to stay as a list of dicts for compatibility with the metadata.py file (templated).
     universal_parameters = [
         {
             'name': 'pretty', 'type': 'boolean', 'choices': None, 'default': False, 'multivalued': False,
             'description': 'The JSON body of the HTTP response will be re-formatted with 2-space indentation',
         },
     ]
+    
     # this key is used to store users' raw input params in the parameter dict 
     # even after "refinement" (i.e., casting to proper data types)
     _RAW_PARAMS_KEY = "#RAW#"
@@ -41,25 +43,30 @@ class ClamsApp(ABC):
     def __init__(self):
         self.metadata: AppMetadata = self._load_appmetadata()
         super().__init__()
-        # data type specification for common parameters
-        python_type = {"boolean": bool, "number": float, "integer": int, "string": str}
-
+        
+        # data type spec to be used in type caster
         self.metadata_param_spec = {}
         self.annotate_param_spec = {}
         for param in ClamsApp.universal_parameters:
-            self.metadata.add_parameter(**param)
-            self.metadata_param_spec[param['name']] = (python_type[param['type']], param.get('multivalued', False))
+            # in addition to building the param spec, add them as regular params, so they are serialized in metadata
+            self.metadata.add_parameter(**param)  
+            self.metadata_param_spec[param['name']] = (param['type'], param.get('multivalued', False))
         for param_spec in self.metadata.parameters:
-            self.annotate_param_spec[param_spec.name] = (python_type[param_spec.type], param_spec.multivalued)
+            self.annotate_param_spec[param_spec.name] = (param_spec.type, param_spec.multivalued)
+
+        self.metadata_param_caster = ParameterCaster(self.metadata_param_spec)
+        self.annotate_param_caster = ParameterCaster(self.annotate_param_spec)
         self.logger = logging.getLogger(self.metadata.identifier)
         
-    def appmetadata(self, **kwargs) -> str:
+    def appmetadata(self, **kwargs: List[str]) -> str:
         """
         A public method to get metadata for this app as a string.
 
         :return: Serialized JSON string of the metadata
         """
-        pretty = kwargs.pop('pretty') if 'pretty' in kwargs else False
+        # cast only, no refinement
+        casted = self.metadata_param_caster.cast(kwargs)
+        pretty = casted.pop('pretty') if 'pretty' in casted else False
         return self.metadata.jsonify(pretty)
     
     def _load_appmetadata(self) -> AppMetadata:
@@ -98,7 +105,7 @@ class ClamsApp(ABC):
     def _check_mmif_compatibility(target_specver, input_specver):
         return target_specver.split('.')[:2] == input_specver.split('.')[:2]
 
-    def annotate(self, mmif: Union[str, dict, Mmif], **runtime_params) -> str:
+    def annotate(self, mmif: Union[str, dict, Mmif], **runtime_params: List[str]) -> str:
         """
         A public method to invoke the primary app function. It's essentially a
         wrapper around :meth:`~clams.app.ClamsApp._annotate` method where some common operations
@@ -108,21 +115,22 @@ class ClamsApp(ABC):
         :param runtime_params: An arbitrary set of k-v pairs to configure the app at runtime
         :return: Serialized JSON string of the output of the app
         """
-        pretty = runtime_params.get('pretty', False)
         if not isinstance(mmif, Mmif):
             mmif = Mmif(mmif)
         issued_warnings = []
         for key in runtime_params:
             if key not in self.annotate_param_spec:
                 issued_warnings.append(UserWarning(f'An undefined parameter "{key}" (value: "{runtime_params[key]}") is passed'))
-        refined_params = self._refine_params(**runtime_params)
+        # this will do casting + refinement altogether
+        refined = self._refine_params(**runtime_params)
+        pretty = refined.get('pretty', False)
         with warnings.catch_warnings(record=True) as ws:
-            annotated = self._annotate(mmif, **refined_params)
+            annotated = self._annotate(mmif, **refined)
             if ws:
                 issued_warnings.extend(ws)
         if issued_warnings:
             warnings_view = annotated.new_view()
-            self.sign_view(warnings_view, refined_params)
+            self.sign_view(warnings_view, runtime_params)
             warnings_view.metadata.warnings = issued_warnings
         return annotated.serialize(pretty=pretty, sanitize=True)
 
@@ -148,7 +156,7 @@ class ClamsApp(ABC):
         """
         raise NotImplementedError()
     
-    def _refine_params(self, **runtime_params):
+    def _refine_params(self, **runtime_params: List[str]):
         """
         Method to "fill" the parameter dictionary with default values, when a key-value is not specified in the input.
         The input map is not really "filled" as a copy of it is returned with addition of default values. 
@@ -159,19 +167,21 @@ class ClamsApp(ABC):
         if self._RAW_PARAMS_KEY in runtime_params:
             # meaning the dict is already refined, just return it 
             return runtime_params
-        conf = {}
+        refined = {}
+        
+        casted = self.annotate_param_caster.cast(runtime_params)
         for parameter in self.metadata.parameters:
-            if parameter.name in runtime_params:
-                if parameter.choices and runtime_params[parameter.name] not in parameter.choices:
+            if parameter.name in casted:
+                if parameter.choices and casted[parameter.name] not in parameter.choices:
                     raise ValueError(f"Value for parameter \"{parameter.name}\" must be one of {parameter.choices}.")
-                conf[parameter.name] = runtime_params[parameter.name]
+                refined[parameter.name] = casted[parameter.name]
             elif parameter.default is not None:
-                conf[parameter.name] = parameter.default
+                refined[parameter.name] = parameter.default
             else:
                 raise ValueError(f"Cannot find configuration for a required parameter \"{parameter.name}\".")
         # raw input params are hidden under a special key
-        conf[self._RAW_PARAMS_KEY] = runtime_params
-        return conf
+        refined[self._RAW_PARAMS_KEY] = runtime_params
+        return refined
     
     def get_configuration(self, **runtime_params):
         warnings.warn("ClamsApp.get_configuration() is deprecated. "
@@ -197,15 +207,26 @@ class ClamsApp(ABC):
                           "no longer be optional in the future. Please pass `runtime_params` "
                           "from _annotate() method.",
                           FutureWarning, stacklevel=2)
+            return
         view.metadata.app = self.metadata.identifier
-        if runtime_conf is not None:
-            if self._RAW_PARAMS_KEY in runtime_conf:
-                conf = runtime_conf[self._RAW_PARAMS_KEY]
-            else:
-                conf = runtime_conf
-            view.metadata.add_parameters(**{k: str(v) for k, v in conf.items()})
+        if self._RAW_PARAMS_KEY in runtime_conf:
+            for k, v in runtime_conf.items():
+                if k == self._RAW_PARAMS_KEY:
+                    for orik, oriv in v.items():
+                        if orik in self.metadata.parameters and self.metadata.parameters[orik].multivalued:
+                            view.metadata.add_parameter(orik, str(oriv))
+                        else:
+                            view.metadata.add_parameter(orik, oriv[0])
+                view.metadata.add_app_configuration(k, v)
+        else:
+            # meaning the parameters directly from flask or argparser and values are in lists
+            for k, v in runtime_conf.items():
+                if k in self.metadata.parameters and self.metadata.parameters[k].multivalued:
+                    view.metadata.add_parameter(k, str(v))
+                else:
+                    view.metadata.add_parameter(k, v[0])
         
-    def set_error_view(self, mmif: Union[str, dict, Mmif], runtime_conf: Optional[dict] = None) -> Mmif:
+    def set_error_view(self, mmif: Union[str, dict, Mmif], **runtime_conf: List[str]) -> Mmif:
         """
         A method to record an error instead of annotation results in the view
         this app generated. For logging purpose, the runtime parameters used
@@ -282,3 +303,102 @@ class ClamsApp(ABC):
                         document_file.close()
                 else:
                     raise FileNotFoundError(p.path)
+
+
+class ParameterCaster(object):
+
+    def __init__(self, param_spec: Dict[str, Tuple[str, bool]]):
+        """
+        A helper class to convert parameters passed by HTTP query strings to
+        proper python data types.
+
+        :param param_spec: A specification of a data types of parameters
+        """
+        self.param_spec = {pname: (python_type[ptype_str], pmultivalued) 
+                           for pname, (ptype_str, pmultivalued) in param_spec.items()}
+
+    def cast(self, args: Dict[str, List[str]]) \
+            -> Dict[str, Union[real_valued_primitives, List[real_valued_primitives], Dict[str, str]]]:
+        """
+        Given parameter specification, tries to cast values of args to specified Python data types.
+        Note that this caster deals with query strings, thus all keys and values in the input args are plain strings. 
+        Also note that the caster does not handle "unexpected" parameters came as an input. 
+        Handling (raising an exception or issuing a warning upon receiving) an unexpected runtime parameter 
+        must be done within the app itself.
+        Thus, when a key is not found in the parameter specifications, it should just pass it as a vanilla string.
+
+        :param args: k-v pairs
+        :return: A new dictionary of type-casted args, of which keys are always strings (parameter name), 
+                 and values are either 
+                 1) a single value of a specified type (multivalued=False)
+                 2) a list of values of a specified type (multivalued=True) (all duplicates in the input are kept)
+                 3) a nested string-string dictionary (type=map ⊨ multivalued=True)
+                 With the third case, developers can further process the nested values into a more complex data types or
+                 structures, but that is not in the scope of this Caster class. 
+        """
+        casted = {}
+        for k, vs in args.items():
+            assert isinstance(vs, list), f"Expected a list of values for key {k}, but got {vs} of type {type(vs)}"
+            assert all(isinstance(v, str) for v in vs), f"Expected a list of strings for key {k}, but got {vs} of types {[type(v) for v in vs]}"
+            if k in self.param_spec:
+                for v in vs:
+                    valuetype, multivalued = self.param_spec[k]
+                    if multivalued or k not in casted:  # effectively only keeps the first value for non-multi params
+                        if valuetype == bool:
+                            v = self.bool_param(v)
+                        elif valuetype == float:
+                            v = self.float_param(v)
+                        elif valuetype == int:
+                            v = self.int_param(v)
+                        elif valuetype == str:
+                            v = self.str_param(v)
+                        elif valuetype == dict:
+                            v = self.kv_param(v)
+                        if multivalued:
+                            if valuetype == dict:
+                                casted.setdefault(k, {}).update(v)
+                            else:
+                                casted.setdefault(k, []).append(v)
+                        else: 
+                            casted[k] = v
+            else:
+                if len(vs) > 1:
+                    casted[k] = vs
+                else:
+                    casted[k] = vs[0]
+        return casted  # pytype: disable=bad-return-type
+
+    @staticmethod
+    def bool_param(value) -> bool:
+        """
+        Helper function to convert string values to bool type.
+        """
+        return False if value in (False, 0, 'False', 'false', '0') else True
+
+    @staticmethod
+    def float_param(value) -> float:
+        """
+        Helper function to convert string values to float type.
+        """
+        return float(value)
+
+    @staticmethod
+    def int_param(value) -> int:
+        """
+        Helper function to convert string values to int type.
+        """
+        return int(value)
+
+    @staticmethod
+    def str_param(value) -> str:
+        """
+        Helper function to convert string values to string type.
+        """
+        return value
+    
+    @staticmethod
+    def kv_param(value) -> Dict[str, str]:
+        """
+        Helper function to convert string values to key-value pair type.
+        """
+        return dict([value.split(map_param_kv_delimiter, 1)])

{clams-python-1.1.3 → clams-python-1.1.5}/clams/appmetadata/__init__.py

@@ -1,7 +1,7 @@
 import os
+import shutil
 import subprocess
 import sys
-import shutil
 from pathlib import Path
 from typing import Union, Dict, List, Optional, Literal
 
@@ -14,7 +14,12 @@ app_version_envvar_key = 'CLAMS_APP_VERSION'
 # type aliases to use in app metadata and runtime parameter processing 
 real_valued_primitives = Union[int, float, bool, str]
 # these names are taken from the JSON schema data types
-param_value_types = Literal['integer', 'number', 'string', 'boolean']
+param_value_types = Literal['integer', 'number', 'string', 'boolean', 'map']
+# and the specific delimiter for the map type
+map_param_kv_delimiter = ':'
+
+# dict to map app parameter data types to Python data types
+python_type = {"boolean": bool, "number": float, "integer": int, "string": str, "map": dict}
 
 param_value_types_values = param_value_types.__args__  # pytype: disable=attribute-error
 app_directory_baseurl = "http://apps.clams.ai"
@@ -38,9 +43,12 @@ def generate_app_version(cwd=None):
     gitcmd = shutil.which('git') 
     gitdir = (Path(sys.modules["__main__"].__file__).parent.resolve() if cwd is None else Path(cwd)) / '.git'
     if gitcmd is not None and gitdir.exists():
-        proc = subprocess.run([gitcmd, '--git-dir', str(gitdir), 'describe', '--tags', '--always'], 
-                              capture_output=True, check=True)
-        return proc.stdout.decode('utf8').strip()
+        try:
+            proc = subprocess.run([gitcmd, '--git-dir', str(gitdir), 'describe', '--tags', '--always'], 
+                                  capture_output=True, check=True)
+            return proc.stdout.decode('utf8').strip()
+        except subprocess.CalledProcessError:
+            return unresolved_app_version_num
     elif app_version_envvar_key in os.environ:
         return os.environ[app_version_envvar_key]
     else:
@@ -65,20 +73,29 @@ class Output(_BaseModel):
     Data model that describes output specification of a CLAMS app. 
     
     CLAMS apps are expected to have at least one output type, and each type must
-    be defined by a ``@type`` URI string. If the type has specific properties and values, 
+    be defined by a ``@type`` URI string. If the type has common properties and values generated by the app, 
     they can be described in the (optional) ``properties`` field. Finally, a human-readable 
     verbose description can be provided in the (optional) ``description`` field for users.
     
-    Developers should take diligent care to include all output types and their properties in the app metadata. 
+    Developers should take diligent care to include all output types and their properties in the app metadata. To 
+    specify the property values, developers can use an actual value (for full match) or ``'*'`` (for any value).
     """
     at_type: pydantic.AnyHttpUrl = pydantic.Field(
         ..., 
         alias="@type", 
         description="The type of the object. Must be a IRI string."
     )
+    description: Optional[str] = pydantic.Field(
+        None,
+        description="A verbose, human-readable description of the type. This is intended to be used for documentation "
+                    "purpose for a particular use case of this annotation type and is not expected to be consumed by "
+                    "software. This description should work as a guideline for users to understand the output type, "
+                    "and also can be used as a expansion specification for the type definition beyond the base "
+                    "vocabulary."
+    )
     properties: Dict[str, real_valued_primitives] = pydantic.Field(
         {}, 
-        description="(optional) Specification for type properties, if any."
+        description="(optional) Specification for type properties, if any. ``\"*\"`` indicates any value."
     )
     
     @pydantic.validator('at_type', pre=True)
@@ -91,18 +108,24 @@ class Output(_BaseModel):
         title = 'CLAMS Output Specification'
         extra = 'forbid'
         allow_population_by_field_name = True
+    
+    def add_description(self, description: str):
+        """
+        Add description string to the type specification.
+        """
+        self.description = description
 
                 
 class Input(Output):
     """
     Data model that describes input specification of a CLAMS app. 
     
-    CLAMS apps are expected to have at least one output type, and each type must
-    be defined by a ``@type`` URI string. If the type has specific properties and values, 
+    CLAMS apps are expected to have at least one input type, and each type must
+    be defined by a ``@type`` URI string. If the type has specific properties and values required by the app, 
     they can be described in the (optional) ``properties`` field. Finally, a human-readable 
     verbose description can be provided in the (optional) ``description`` field for users.
     
-    Developers should take diligent care to include all output types and their properties in the app metadata. 
+    Developers should take diligent care to include all input types and their properties in the app metadata. 
     """
     required: bool = pydantic.Field(
         None, 
@@ -138,16 +161,33 @@ class RuntimeParameter(_BaseModel):
     )
     type: param_value_types = pydantic.Field(
         ...,
-        description=f"Type of the parameter value the app expects. Must be one of {param_value_types_values}."
+        description=f"Type of the parameter value the app expects. Must be one of {param_value_types_values}. When "
+                    "type is ``map``, ``multivalued=true`` is automatically forced. \n\n"
+                    "Notes for developers: \n\n"
+                    "When the type is ``map``, the parameter value (still a single string from the users' perspective) "
+                    "must be formatted as a ``KEY:VALUE`` pair, namely a colon-separated string. To pass multiple "
+                    "key-value pairs, users need to pass the parameter multiple times (remember ``type=map`` implies "
+                    "``multivalued=true``) with pairs in the colon-separated format. \n\n"
+                    "Also, the `VALUE` part of the user input is always expected and handled as a string. If a "
+                    "developers wants to do more text processing on the passed value to accept more complex data types "
+                    "or structures (e.g., map from a string to a list of strings), it is up to the developer. However, "
+                    "any additional form requirements should be precisely described in the ``description`` field for "
+                    "users. \n\n"
+                    "Finally, the same format is expected for the default value, if any. For example, if the default "
+                    "desired dictionary is ``{'key1': 'value1', 'key2': 'value2'}``, the default value (used when "
+                    "initializing a parameter) should be ``['key1:value1','key2:value2']``\n."
     ) 
     choices: List[real_valued_primitives] = pydantic.Field(
         None, 
         description="(optional) List of string values that can be accepted."
     )
-    default: real_valued_primitives = pydantic.Field(
+    default: Union[real_valued_primitives, List[real_valued_primitives]] = pydantic.Field(
         None, 
-        description="(optional) Default value for the parameter. Only valid for optional parameters. Namely, setting "
-                    "a default value makes a parameter 'optional'."
+        description="(optional) Default value for the parameter.\n\n"
+                    "Notes for developers: \n\n"
+                    "Setting a default value makes a parameter `optional`. \n\n"
+                    "When ``multivalued=True``, the default value should be a list of values. \n\n"
+                    "When ``type=map``, the default value should be a list of colon-separated strings. \n\n"
     )
     multivalued: bool = pydantic.Field(
         ..., 
@@ -157,8 +197,15 @@ class RuntimeParameter(_BaseModel):
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
+        if self.type == 'map':
+            if self.multivalued is False:
+                raise ValueError("When the type is `map`, multivalued must not be False.")
+            else:
+                self.multivalued = True
         if self.multivalued is None:
             self.multivalued = False
+        if self.multivalued and self.default is not None and not isinstance(self.default, list):
+            self.default = [self.default]
             
     class Config:
         title = 'CLAMS App Runtime Parameter'
@@ -301,13 +348,14 @@ class AppMetadata(pydantic.BaseModel):
                     return True
         return False
 
-    def add_input(self, at_type: Union[str, vocabulary.ThingTypesBase], required: bool = True, **properties):
+    def add_input(self, at_type: Union[str, vocabulary.ThingTypesBase], required: bool = True, **properties) -> Input:
         """
         Helper method to add an element to the ``input`` list. 
         
         :param at_type: ``@type`` of the input object
         :param required: whether this type is mandatory or optional 
         :param properties: additional property specifications
+        :return: the newly added Input object
         """
         new = Input(at_type=at_type, required=required)
         if len(properties) > 0:
@@ -320,8 +368,9 @@ class AppMetadata(pydantic.BaseModel):
                 # TODO (krim @ 5/12/21): automatically add *optional* input types to parameter
                 # see https://github.com/clamsproject/clams-python/issues/29 for discussion
                 pass
+        return new
 
-    def add_input_oneof(self, *inputs: Union[str, Input, vocabulary.ThingTypesBase] ):
+    def add_input_oneof(self, *inputs: Union[str, Input, vocabulary.ThingTypesBase]):
         newinputs = []
         if len(inputs) == 1:
             if isinstance(inputs[0], Input):
@@ -342,12 +391,13 @@ class AppMetadata(pydantic.BaseModel):
                     newinputs.append(i)
             self.input.append(newinputs)
 
-    def add_output(self, at_type: Union[str, vocabulary.ThingTypesBase], **properties):
+    def add_output(self, at_type: Union[str, vocabulary.ThingTypesBase], **properties) -> Output:
         """
         Helper method to add an element to the ``output`` list. 
         
         :param at_type: ``@type`` of the input object
         :param properties: additional property specifications
+        :return: the newly added Output object
         """
         new = Output(at_type=at_type)
         if len(properties) > 0:
@@ -356,21 +406,31 @@ class AppMetadata(pydantic.BaseModel):
             self.output.append(new)
         else:
             raise ValueError(f"Cannot add a duplicate output '{new}'.")
+        return new
 
     def add_parameter(self, name: str, description: str, type: param_value_types,
                       choices: Optional[List[real_valued_primitives]] = None,
                       multivalued: bool = False,
-                      default: real_valued_primitives = None):
+                      default: Union[real_valued_primitives, List[real_valued_primitives]] = None):
         """
         Helper method to add an element to the ``parameters`` list. 
         """
-        # casting default values (when the value is not nothing) makes sure 
-        # the values are correctly casted by the pydantic
+        # casting default values (when the value is not nothing) to str 
+        # will make sure the values are correctly handled by the pydantic
         # see https://docs.pydantic.dev/1.10/usage/types/#unions
         # e.g. casting 0.1 using the `primitives` dict will result in  0 (int)
         # while casting "0.1" using the `primitives` dict will result in  0.1 (float)
-        new_param = RuntimeParameter(name=name, description=description, type=type,
-                                     choices=choices, default=str(default) if default else default, multivalued=multivalued)
+        if type == 'map' and multivalued is False:
+            multivalued = True
+        if default is not None:
+            if isinstance(default, list):
+                default = [str(d) for d in default]
+            else:
+                default = str(default)
+            
+        new_param = RuntimeParameter(
+            name=name, description=description, type=type, choices=choices, multivalued=multivalued,
+            default=default)
         if new_param.name not in [param.name for param in self.parameters]:
             self.parameters.append(new_param)
         else:

{clams-python-1.1.3 → clams-python-1.1.5}/clams/restify/__init__.py

@@ -1,12 +1,9 @@
-from typing import Dict, Union, Any, Tuple, List
-
 import jsonschema
 from flask import Flask, request, Response
 from flask_restful import Resource, Api
 from mmif import Mmif
 
 from clams.app import ClamsApp
-from clams.appmetadata import real_valued_primitives
 
 
 class Restifier(object):
@@ -107,8 +104,6 @@ class ClamsHTTPApi(Resource):
     def __init__(self, cla_instance: ClamsApp):
         super().__init__()
         self.cla = cla_instance
-        self.metadata_param_caster = ParameterCaster(self.cla.metadata_param_spec)  # pytype: disable=wrong-arg-types
-        self.annotate_param_caster = ParameterCaster(self.cla.annotate_param_spec)  # pytype: disable=wrong-arg-types
 
     @staticmethod
     def json_to_response(json_str: str, status=200) -> Response:
@@ -129,7 +124,7 @@ class ClamsHTTPApi(Resource):
 
         :return: Returns app metadata in a HTTP response.
         """
-        return self.json_to_response(self.cla.appmetadata(**self.metadata_param_caster.cast(request.args)))
+        return self.json_to_response(self.cla.appmetadata(**request.args))
 
     def post(self) -> Response:
         """
@@ -138,93 +133,16 @@ class ClamsHTTPApi(Resource):
 
         :return: Returns MMIF output from a ClamsApp in a HTTP response.
         """
-        raw_data = request.get_data()
+        raw_data = request.get_data().decode('utf-8')
         # this will catch duplicate arguments with different values into a list under the key
-        raw_params = request.args.to_dict(False)
+        raw_params = request.args.to_dict(flat=False)
         try:
             _ = Mmif(raw_data)
         except jsonschema.exceptions.ValidationError as e:
             return Response(response="Invalid input data. See below for validation error.\n\n" + str(e), status=500, mimetype='text/plain')
         try:
-            return self.json_to_response(self.cla.annotate(raw_data, **self.annotate_param_caster.cast(raw_params)))
-        except Exception as e:
-            return self.json_to_response(self.cla.record_error(raw_data, self.annotate_param_caster.cast(raw_params)).serialize(pretty=True), status=500)
+            return self.json_to_response(self.cla.annotate(raw_data, **raw_params))
+        except Exception:
+            return self.json_to_response(self.cla.record_error(raw_data, **raw_params).serialize(pretty=True), status=500)
 
     put = post
-
-
-class ParameterCaster(object):
-    """
-    A helper class to convert parameters passed by HTTP query strings to
-    proper python data types.
-
-    :param param_spec: A specification of a data types of parameters
-    """
-    def __init__(self, param_spec: Dict[str, Tuple[real_valued_primitives, bool]]):
-        self.param_spec = param_spec
-
-    def cast(self, args: Dict[str, List[str]]) -> Dict[str, Union[real_valued_primitives, List[real_valued_primitives]]]:
-        """
-        Given parameter specification, tries to cast values of args to specified Python data types.
-        Note that this caster deals with query strings, thus all keys and values in the input args are plain strings. 
-        Also note that the caster does not handle "unexpected" parameters came as an input. 
-        Handling (raising an exception or issuing a warning upon receiving) an unexpected runtime parameter 
-        must be done within the app itself.
-        Thus, when a key is not found in the parameter specifications, it should just pass it as a vanilla string.
-
-        :param args: k-v pairs
-        :return: A new dictionary of type-casted args
-        """
-        casted = {}
-        for k, vs in args.items():
-            if k in self.param_spec:
-                for v in vs:
-                    type_, multivalued = self.param_spec[k]
-                    if multivalued or k not in casted:  # effectively only keeps the first value for non-multi params
-                        if type_ == bool:
-                            v = self.bool_param(v)
-                        elif type_ == float:
-                            v = self.float_param(v)
-                        elif type_ == int:
-                            v = self.int_param(v)
-                        elif type_ == str:
-                            v = self.str_param(v)
-                        if multivalued:
-                            casted.setdefault(k, []).append(v)
-                        else: 
-                            casted[k] = v
-            else:
-                if len(vs) > 1:
-                    casted[k] = vs
-                else:
-                    casted[k] = vs[0]
-                    
-        return casted
-
-    @staticmethod
-    def bool_param(value):
-        """
-        Helper function to convert string values to bool type.
-        """
-        return False if value in (False, 0, 'False', 'false', '0') else True
-
-    @staticmethod
-    def float_param(value):
-        """
-        Helper function to convert string values to float type.
-        """
-        return float(value)
-
-    @staticmethod
-    def int_param(value):
-        """
-        Helper function to convert string values to int type.
-        """
-        return int(value)
-
-    @staticmethod
-    def str_param(value):
-        """
-        Helper function to convert string values to string type.
-        """
-        return value

clams-python-1.1.5/clams/ver/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.5"

{clams-python-1.1.3 → clams-python-1.1.5/clams_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clams-python
-Version: 1.1.3
+Version: 1.1.5
 Summary: A collection of APIs to develop CLAMS app for python
 Home-page: https://clams.ai
 Author: Brandeis Lab for Linguistics and Computation
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mmif-python==1.0.10
+Requires-Dist: mmif-python==1.0.11
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

{clams-python-1.1.3 → clams-python-1.1.5}/clams_python.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mmif-python==1.0.10
+mmif-python==1.0.11
 Flask>=2
 Flask-RESTful>=0.3.9
 gunicorn>=20

{clams-python-1.1.3 → clams-python-1.1.5}/requirements.txt

@@ -1,4 +1,4 @@
-mmif-python==1.0.10
+mmif-python==1.0.11
 
 Flask>=2
 Flask-RESTful>=0.3.9

{clams-python-1.1.3 → clams-python-1.1.5}/tests/test_clamsapp.py

@@ -13,8 +13,8 @@ from mmif import Mmif, Document, DocumentTypes, AnnotationTypes, View, __specver
 
 import clams.app
 import clams.restify
+from clams.app import ParameterCaster
 from clams.appmetadata import AppMetadata, Input
-from clams.restify import ParameterCaster
 
 
 class ExampleInputMMIF(object):
@@ -123,7 +123,7 @@ class TestClamsApp(unittest.TestCase):
         self.assertTrue('properties' not in elem)
         self.assertTrue(elem['required'])
         
-        # test add_X methods
+    def test_metadata_inputoutput(self):
         self.app.metadata.add_output(AnnotationTypes.BoundingBox, boxType='text')
         metadata = json.loads(self.app.appmetadata())
         self.assertEqual(len(metadata['output']), 2)
@@ -132,11 +132,22 @@ class TestClamsApp(unittest.TestCase):
             self.app.metadata.add_input(at_type=DocumentTypes.TextDocument)
         with self.assertRaises(ValueError):
             self.app.metadata.add_output(AnnotationTypes.BoundingBox, boxType='text')
-        # but this should 
-        self.app.metadata.add_output(AnnotationTypes.BoundingBox, boxType='face')
+        # but this should, even when there's `BoundingBox` already because the boxType prop value is different
+        face_bb_out = self.app.metadata.add_output(AnnotationTypes.BoundingBox, boxType='face')
+        # with an optional "comment"
+        face_bb_out.description = 'face bounding box'
+        # then should be able to set the description of the existing output
+        text_bb_out = next(o for o in self.app.metadata.output if o.properties.get('boxType') == 'text')
+        text_bb_out.description = 'text bounding box'
         metadata = json.loads(self.app.appmetadata())
         self.assertEqual(len(metadata['input']), 2)
-        self.assertTrue('properties' not in metadata['input'][0])
+        for i in metadata['input']:
+            self.assertTrue('properties' not in i)
+            self.assertTrue('description' not in i)
+        for o in metadata['output']:
+            if o['@type'] == AnnotationTypes.BoundingBox:
+                self.assertTrue('properties' in o)
+                self.assertTrue('description' in o)
         # adding input with properties
         self.app.metadata.add_input(at_type=AnnotationTypes.TimeFrame, frameType='speech')
         metadata = json.loads(self.app.appmetadata())
@@ -151,19 +162,42 @@ class TestClamsApp(unittest.TestCase):
         j = Input(at_type=AnnotationTypes.VideoObject)
         with self.assertRaises(ValueError):
             self.app.metadata.add_input_oneof(i, j)
+    
+    def test_metadata_runtimeparams(self):
         # now parameters
+        num_params = 1  # starts with `raise_error` in metadata.py
         # using a custom class
         # this should conflict with existing parameter
         with self.assertRaises(ValueError):
             self.app.metadata.add_parameter(
                 name='raise_error', description='force raise a ValueError', 
                 type='boolean', default='false')
-        # using python dict
+            num_params += 0
+            
+        # some random multiple choice parameters
         self.app.metadata.add_parameter(
-            name='multiple_choice', description='meaningless multiple choice option',
+            name='single_choice', description='meaningless choice for a single value',
+            type='integer', choices=[1, 2, 3, 4, 5], default='3', multivalued=False)
+        num_params += 1
+
+        self.app.metadata.add_parameter(
+            name='multiple_choice', description='meaningless choice for any number of values',
             type='integer', choices=[1, 2, 3, 4, 5], default=3, multivalued=True)
+        num_params += 1
+        
         metadata = json.loads(self.app.appmetadata())
-        self.assertEqual(len(metadata['parameters']), 2 + len(self.app.universal_parameters))
+        self.assertEqual(len(metadata['parameters']), num_params + len(self.app.universal_parameters))
+
+        for p in metadata['parameters']:
+            # default value must match the data type
+            if p['name'] == 'single_choice':
+                self.assertFalse(p['multivalued'])
+                self.assertTrue(isinstance(p['default'], int))
+            # default for multivalued para must be a list 
+            if p['name'] == 'multiple_choice':
+                self.assertTrue(p['multivalued'])
+                self.assertTrue(isinstance(p['default'], list))
+                self.assertEqual(len(p['default']), 1)
         # now more additional metadata
         self.app.metadata.add_more('one', 'more')
         self.assertEqual(self.app.metadata.more['one'], 'more')
@@ -173,7 +207,7 @@ class TestClamsApp(unittest.TestCase):
             self.app.metadata.add_more('one', '')
         
         # finally for an eye exam
-        print(self.app.appmetadata(pretty=True))
+        print(self.app.appmetadata(pretty=['true']))
 
     @pytest.mark.skip('legacy type version check')
     def test__check_mmif_compatibility(self):
@@ -205,7 +239,7 @@ class TestClamsApp(unittest.TestCase):
         for v in out_mmif.views:
             if v.metadata.app == self.app.metadata.identifier:
                 self.assertEqual(len(v.metadata.parameters), 0)  # no params were passed when `annotate()` was called
-        out_mmif = self.app.annotate(self.in_mmif, pretty=False)
+        out_mmif = self.app.annotate(self.in_mmif, pretty=[str(False)])
         out_mmif = Mmif(out_mmif)
         for v in out_mmif.views:
             if v.metadata.app == self.app.metadata.identifier:
@@ -226,8 +260,6 @@ class TestClamsApp(unittest.TestCase):
         self.app._annotate = MagicMock(return_value=m)
         with self.assertRaises(jsonschema.ValidationError):
             self.app.annotate(self.in_mmif)
-        
-        
 
     def test_open_document_location(self):
         mmif = ExampleInputMMIF.get_rawmmif()
@@ -242,40 +274,54 @@ class TestClamsApp(unittest.TestCase):
             
     def test_refine_parameters(self):
         self.app.metadata.parameters = []
-        self.app.metadata.add_parameter('param1', 'first_param', 'string')
-        self.app.metadata.add_parameter('param2', 'second_param', 'string', default='second_default')
-        self.app.metadata.add_parameter('param3', 'third_param', 'boolean', default='f')
-        self.app.metadata.add_parameter('param4', 'fourth_param', 'integer', default='1', choices="1 2 3".split())
-        self.app.metadata.add_parameter('param5', 'fifth_param', 'number', default='0.5')
-        dummy_params = {'param1': 'okay', 'non_parameter': 'should be ignored'}
+        self.app.metadata.add_parameter('param1', type='string',
+                                        description='string -def +req')
+        self.app.metadata.add_parameter('param2', type='string', default='second_default',
+                                        description='stirng +def')
+        self.app.metadata.add_parameter('param3', type='boolean', default='f',
+                                        description='bool +def')
+        self.app.metadata.add_parameter('param4', type='integer', default=1, choices="1 2 3".split(),
+                                        description='int +def +choices')
+        self.app.metadata.add_parameter('param5', type='number', default=0.5,
+                                        description='float +def')
+        self.app.metadata.add_parameter('param6', type='number', multivalued=True, default=[0.5],
+                                        description='float +def +mv')
+        self.app.metadata.add_parameter('param7', type='number', default=[], multivalued=True,
+                                        description='float +def +empty +mv')
+        with self.assertRaises(ValueError):
+            self.app._refine_params(**{})  # param1 is required, but not passed
+        dummy_params = {'param1': ['okay'], 'non_parameter': ['should be ignored']}
         conf = self.app._refine_params(**dummy_params)
         # should not refine what's already refined
         double_refine = self.app._refine_params(**conf)
         self.assertTrue(clams.ClamsApp._RAW_PARAMS_KEY in double_refine)
         self.assertEqual(double_refine, conf)
         conf.pop(clams.ClamsApp._RAW_PARAMS_KEY, None)
-        self.assertEqual(len(conf), 5)  # 1 from `param1`, 4 from default value
+        self.assertEqual(len(conf), 7)  # 1 from `param1`, 6 from default value
         self.assertFalse('non_parameter' in conf)
         self.assertEqual(type(conf['param1']), str)
         self.assertEqual(type(conf['param2']), str)
         self.assertEqual(type(conf['param3']), bool)
         self.assertEqual(type(conf['param4']), int)
         self.assertEqual(type(conf['param5']), float)
+        self.assertEqual(type(conf['param6']), list)
+        self.assertEqual(type(conf['param7']), list)
+        self.assertEqual(len(conf['param7']), 0)
         with self.assertRaises(ValueError):
             # because param1 doesn't have a default value and thus a required param
-            self.app._refine_params(param2='okay')
-        with self.assertRaisesRegexp(ValueError, r'.+must be one of.+'):
+            self.app._refine_params(param2=['okay'])
+        with self.assertRaisesRegex(ValueError, r'.+must be one of.+'):
             # because param4 can't be 4, note that param1 is "required" 
-            self.app._refine_params(param1='p1', param4=4)
+            self.app._refine_params(param1=['p1'], param4=['4'])
             
     def test_error_handling(self):
-        params = {'raise_error': True, 'pretty': True}
+        params = {'raise_error': 'true', 'pretty': 'true'}
         in_mmif = Mmif(self.in_mmif)
         try: 
             out_mmif = self.app.annotate(in_mmif, **params)
         except Exception as e:
-            out_mmif_from_str = self.app.set_error_view(self.in_mmif, params)
-            out_mmif_from_mmif = self.app.set_error_view(in_mmif, params)
+            out_mmif_from_str = self.app.set_error_view(self.in_mmif, **params)
+            out_mmif_from_mmif = self.app.set_error_view(in_mmif, **params)
             self.assertEqual(out_mmif_from_mmif.views, out_mmif_from_str.views)
             out_mmif = out_mmif_from_str
         self.assertIsNotNone(out_mmif)
@@ -374,13 +420,14 @@ class TestRestifier(unittest.TestCase):
 class TestParameterCaster(unittest.TestCase):
     
     def setUp(self) -> None:
-        self.param_spec = {'str_param': (str, False), 
-                           'number_param': (float, False),
-                           'int_param': (int, False),
-                           'bool_param': (bool, False), 
-                           'str_multi_param': (str, True)
+        self.param_spec = {'str_param': ('string', False),
+                           'number_param': ('number', False),
+                           'int_param': ('integer', False),
+                           'bool_param': ('boolean', False),
+                           'str_multi_param': ('string', True),
+                           'map_param': ('map', True),
                            }
-        
+
     def test_cast(self):
         caster = ParameterCaster(self.param_spec)
         params = {
@@ -391,7 +438,9 @@ class TestParameterCaster(unittest.TestCase):
             'str_multi_param': ['value1', 'value2'],
             'undefined_param_single': ['undefined_value1'],
             'undefined_param_multi': ['undefined_value1', 'undefined_value2'],
+            'map_param': ['key1:val1', 'key2:val2', 'key3:val3', 'key1:val4']
         }
+        # all "RAW" parameter values are assumed to be strings
         self.assertTrue(all(map(lambda x: isinstance(x, str), itertools.chain.from_iterable(params.values()))))
         casted = caster.cast(params)
         # must push out to the list
@@ -404,6 +453,11 @@ class TestParameterCaster(unittest.TestCase):
         self.assertTrue('undefined_param_multi' in casted)
         self.assertFalse(isinstance(casted['undefined_param_single'], list))
         self.assertTrue(isinstance(casted['undefined_param_multi'], list))
+        self.assertEqual(3, len(casted['map_param']))
+        self.assertTrue(all(map(lambda x: isinstance(x, str), casted['map_param'].values())))
+        self.assertTrue('val4', len(casted['map_param']['key1']))
+        self.assertTrue('val2', len(casted['map_param']['key2']))
+        self.assertTrue('val3', len(casted['map_param']['key3']))
         unknown_param_key = 'unknown'
         unknown_param_val = 'dunno'
         params[unknown_param_key] = [unknown_param_val]

clams-python-1.1.3/VERSION

@@ -1 +0,0 @@
-1.1.3

clams-python-1.1.3/clams/ver/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.1.3"