Restructure and prune exceptions

doc/wrappers.rst

@@ -1173,6 +1173,7 @@ Exceptions
 ^^^^^^^^^^
 
 Below is a list of all exceptions that the wrappers can raise, together with a summary of the kind of error that occured.
+For each exception, its superclasses are also indicated after the colon.
 
 .. exception:: ModelverseException
 
@@ -1181,7 +1182,138 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
    General Python exceptions could theoretically still occur, though this likely is a bug in the wrapper.
    This exception itself will never occur: it is abstract.
 
-.. exception:: UnknownError
+.. exception:: SuperclassAttribute : ModelverseException
+
+   The attribute that is being modified, was defined in a superclass, even though it is also available for this class.
+   To prevent unexpected changes, the change to the attribute is disallowed and should be invoked on the superclass that actually defines the attribute.
+
+   Examples:
+
+   * Modifying the type of the weight attribute is disallowed, as the attribute was defined on an abstract class for both the P2T and T2P associations.
+
+     >>> attribute_type("formalisms/PetriNets", "P2T", "weight", "Integer")
+     SuperclassAttribute()
+
+.. exception:: CallbackOnEmptySignature : ModelverseException
+
+   An activity is being added which has an empty signature for input and output metamodels, while it still defines an operation on the merged metamodel.
+   As there is no merged metamodel, since there are no models being manipulated, it is impossible to perform the specified operation
+
+   Examples:
+
+   * When adding a manual operation without signature, but providing an operation
+
+     >>> def operation(model):
+     ...     pass
+     >>> transformation_add_MANUAL({}, {}, "users/user/test/a", operation)
+     CallbackOnEmptySignature()
+
+.. exception:: NotAModel : ModelverseException
+
+   The requested location does not contain a model, but is instead a folder, while a model was expected.
+
+   Examples:
+
+   * When creating a new instance of a "folder" metamodel
+
+     >>> model_add("my_new_model", "formalisms")
+     NotAModel()
+
+.. exception:: UserNotInGroup : ModelverseException
+
+   The specified user is not part of the group, whereas it should be a member of this group.
+
+   Examples:
+
+   * When kicking a user from a group, while the user is not even a member.
+
+     >>> group_kick("group_A", "user_B")
+     UserNotInGroup()
+
+.. exception:: IncorrectFormat : ModelverseException
+
+   An incorrect format is specified for some input.
+
+   Examples:
+
+   * When setting the permissions of a model, this should be a string containing three characters representing either 0, 1, or 2.
+
+     >>> permission_modify("formalisms", "003")
+     IncorrectFormat()
+
+   * When querying for all transformations satisfying an input and output signature, they cannot both be empty, as that would return all transformations in the Modelverse.
+
+     >>> transformation_between({}, {})
+     IncorrectFormat()
+
+.. exception:: SignatureMismatch : ModelverseException
+
+   Generic exception for when the signature that is provided does not match the expected signature in the Modelverse.
+   This is superclass for many more specific exceptions, but can also occur in its own right.
+
+   Examples:
+
+   * When executing a process with a model mapping that contains an entry that is not used by the process.
+
+     >>> process_execute("users/user/test/empty_process", {"a": "models/a"})
+     SignatureMismatch()
+
+.. exception:: EmptySignature : SignatureMismatch
+
+   Adding a model transformation with an empty input and output signature is not allowed, as no metamodel can be determined for RAMification and future execution.
+
+   Examples:
+
+   * When adding an empty model transformation.
+
+     >>> transformation_add_MT({}, {}, "users/user/test/a", "...")
+     EmptySignature()
+
+.. exception:: SourceModelNotBound : SignatureMismatch
+
+   Executing an activity with an incomplete input signature.
+
+   Examples:
+
+   * When executing a reachability analysis activity, without specifying the petri net model as input.
+
+     >>> transformation_execute_AL("users/user/reachability_analyse", {}, {"reachability_graph": "users/user/reachability_graph"})
+     SourceModelNotBound()
+
+.. exception:: TargetModelNotBound : SignatureMismatch
+
+   Executing an activity with an over-specified output signature.
+
+   Examples:
+
+   * When executing a reachability analysis activity, a second (undefined) output key is specified in the invocation.
+
+     >>> transformation_execute_AL("users/user/initialize_pn", {}, {"pn": "users/user/pn", "reachability": "users/user/reachability"})
+     TargetModelNotBound()
+
+.. exception:: DifferingModelsForKey : SignatureMismatch
+
+   When the input and output signature of an activity are in conflict, because a key has a different type in the output than the input.
+
+   Examples:
+
+   * If the key A switches type in the input and output signature of a to be created activity.
+
+     >>> transformation_add_MANUAL({"A": "users/user/A"}, {"A": "users/user/B"}, "users/user/activity")
+     DifferingModelsForKey()
+
+.. exception:: TypeMismatch : SignatureMismatch
+
+   The type of a model in the input or output signature does not match with the expected type.
+
+   Examples:
+
+   * When executing an activity that took an instance of "formalisms/PetriNets" as input, gets an instance of "formalisms/ProcessModel" instead.
+
+     >>> transformation_execute_AL("users/user/reachability_analyse", {"PN": "users/user/my_pm"}, {})
+     TypeMismatch()
+
+.. exception:: UnknownError : ModelverseException
 
    Unknown exception has occured.
    This is likely something wrong with the connection, such as the Modelverse that suddenly disconnected, or the request timed out.
@@ -1194,7 +1326,20 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
      >>> element_list("formalisms/PetriNets") # <-- Modelverse killed during execution
      UnknownError()
 
-.. exception:: UnknownIdentifier
+.. exception:: UnknownM3 : ModelverseException
+
+   The M3 level of the model could not be determined, indicating that the metametamodel is not recognized as such.
+
+   Examples:
+
+   * When instantiating a model at the M1 level again
+
+     >>> model_add("M2", "formalisms/SimpleClassDiagrams")
+     >>> model_add("M1", "M2")
+     >>> model_add("wrong", "M1")
+     UnknownM3()
+
+.. exception:: UnknownIdentifier : ModelverseException
 
    The specified element identifier could not be resolved in the specified model in the Modelverse.
    The exception contains the identifier causing the problem, as there might be multiple identifiers used in a single request.
@@ -1209,49 +1354,66 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
    * When reading out the allowed connections between two elements, of which neither exists.
 
      >>> connections_between("models/my_pn", "p0", "t0")
-     UnkownIdentifier("p0")
+     UnknownIdentifier("p0")
 
    * When reading out the allowed connections between two elements, of which the target doesn't exists.
 
      >>> connections_between("models/my_pn", "p1", "t0")
-     UnkownIdentifier("t0")
+     UnknownIdentifier("t0")
 
    * When instantiating a non-existing element in the meta-model.
 
      >>> instantiate("models/my_pn", "CapacityConstrainedPlace")
-     UnkownIdentifier("CapacityConstrainedPlace")
+     UnknownIdentifier("CapacityConstrainedPlace")
 
-.. exception:: UnsupportedValue
+.. exception:: CompilationError : ModelverseException
 
-   The specified value is not a primitive that can be serialized.
-   Supported types are: string, boolean, integer, and float.
+   Error in the HUTN compiler during compilation.
+   This is mostly caused by a malformed expression in the specified code.
+   The compilation error is contained in the content of the exception.
 
    Examples:
 
-   * When assigning a list as attribute.
+   * When assigning a code block which cannot be parsed as action language.
 
-      >>> attr_assign("models/my_pn", "p1", "tokens", [1, 2, 3])
-      UnsupporteValue("[1, 2, 3] : list")
+     >>> attr_assign_code("models/my_pn", "p1", "tokens", "1")
+     CompilationError("Parsing error at line 1: ...")
 
-   * When assigning a None value to an attribute.
+.. exception:: NotAnActivity : ModelverseException
 
-      >>> attr_assign("models/my_pn", "p1", "name", None)
-      UnsupportedValue("None : NoneType")
+   An activity model was expected, but the provided model was not an executable activity.
 
-.. exception:: CompilationError
+   Examples:
 
-   Error in the HUTN compiler during compilation.
-   This is mostly caused by a malformed expression in the specified code.
-   The compilation error is contained in the content of the exception.
+   * When an ordinary model is passed to the transformation execution.
+
+     >>> transformation_execute_AL("formalisms/PetriNets", {}, {})
+     NotAnActivity()
+
+.. exception:: NotAProcess : ModelverseException
+
+   A process model was expected, but the provided model was not typed as such.
 
    Examples:
 
-   * When assigning a code block which cannot be parsed as action language.
+   * When executing an ordinary model as if it were a process.
 
-     >>> attr_assign_code("models/my_pn", "p1", "tokens", "1")
-     CompilationError("Parsing error at line 1: ...")
+     >>> process_execute("formalisms/PetriNets", {})
+     NotAProcess()
 
-.. exception:: NoSuchAttribute
+.. exception:: NotAValidProcess : ModelverseException
+
+   A process model was expected, and received, but it did not completely conform to the metamodel.
+   For example, some constraints were not valid, no initial node was found, and so on.
+
+   Examples:
+
+   * When a process model is being executed that has not a single "Start" instance.
+
+     >>> process_execute("models/my_empty_pm", {})
+     NotAValidProcess()
+
+.. exception:: UnknownAttribute : UnknownIdentifier
 
    The specified attribute does not exist for this element.
    While the attribute might exist as a type for the lower meta-level, this only looks at the current level.
@@ -1261,9 +1423,17 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
    * When assigning a non-existing attribute.
 
      >>> attr_assign("models/my_pn", "p1", "capacity", 2)
-     NoSuchAttribute("capacity")
+     UnknownAttribute("capacity")
+
+.. exception:: UnknownElement : UnknownIdentifier
+
+   Examples:
+
+   * 
+
+     >>>
 
-.. exception:: UnknownModel
+.. exception:: UnknownModel : UnknownIdentifier
 
    The specified model can not be resolved in the Modelverse.
    While the model might technically exist, this exception merely indicates that it cannot be referred to with the specified identifier.
@@ -1275,7 +1445,31 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
      >>> transformation_execute_MT("models/pn_optimize", {"pn": "models/my_pn"}, {"pn": "models/my_optimized_pn"})
      UnknownModel("pn_optimize")
 
-.. exception:: ConnectionError
+.. exception:: UnknownLocation : UnknownIdentifier
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: UnknownGroup : UnknownIdentifier
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: UnknownUser : UnknownIdentifier
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: ConnectionError : ModelverseException
 
    Error during initialization of the connection to the Modelverse.
    The actual error is enclosed in the exception content.
@@ -1287,9 +1481,33 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
    * When trying to connect to a server which doesn't exist.
 
      >>> init("http://www.modelverse.be")
-     ConnectionError("No such host")
+     ConnectionError()
+
+.. exception:: ExistsError : ModelverseException
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: AttributeExists : ExistsError
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: ElementExists : ExistsError
+
+   Examples:
+
+   * 
+
+     >>>
 
-.. exception:: ModelExists
+.. exception:: ModelExists : ExistsError
 
    The identifier to give to the newly created model already exists.
    Note that some operations, such as model transformation, will default to overwriting a model if it already exists, but still is used as a target.
@@ -1302,62 +1520,109 @@ Below is a list of all exceptions that the wrappers can raise, together with a s
      >>> model_add("models/my_pn", "PetriNets")
      ModelExists("models/my_pn")
 
-.. exception:: PermissionDenied
+.. exception:: FolderExists : ExistsError
 
-   Permission denied to either write or read the specified resource.
-   This resource can be anything: a model, an element, a user, a group, ...
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: GroupExists : ExistsError
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: UserExists : ExistsError
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: PermissionDenied : ModelverseException
 
    Examples:
 
-   * When changing the password of another user, while we are not an administrator.
+   * 
 
-     >>> user_password("user2", "NewPassword")
-     PermissionDenied("user2")
+     >>>
 
-   * When listing the elements of a model which we aren't allowed to read.
+.. exception:: ReadPermissionDenied : PermissionDenied
 
-     >>> element_list("models/secret_model")
-     PermissionDenied("models/secret_model")
+   Examples:
+
+   * 
 
-   * When altering a model which we are only allowed to read.
+     >>>
 
-     >>> instantiate("formalisms/SimpleClassDiagrams", "NewClass")
-     PermissionDenied("formalisms/SimpleClassDiagrams")
+.. exception:: WritePermissionDenied : PermissionDenied
 
-.. exception:: InvalidMode
+   Examples:
 
-   An operation was executed in the wrong context.
-   For example, all operations are only valid after a successful *init* and *login* call.
-   This error can also result from a previous exception, which wasn't handled correctly.
+   * 
+
+     >>>
+
+.. exception:: ExecutePermissionDenied : PermissionDenied
 
    Examples:
 
-   * When a *login* fails (thus raising a *PermissionDenied* exception), but the next operation assumes that the user is logged in.
+   * 
 
-     >>> login("admmin", "wrong_password")
-     PermissionDenied("admin")
-     >>> element_list("formalisms/SimpleClassDiagrams")
-     InvalidMode()
+     >>>
 
-.. exception:: InterfaceMismatch
+.. exception:: UserPermissionDenied : PermissionDenied
 
-   The Modelverse responded with an unexpected response.
-   As a response came, the Modelverse is likely still running, though we have no idea how to interpret the result.
-   Likely, the wrapper is not up to date with the latest Modelverse operations.
-   It is difficult to give an example, as this always indicates a bug in the wrapper itself.
+   Examples:
 
-.. exception:: UnknownMetamodellingHierarchy
+   * 
 
-   The requested model and metamodel have no existing relation between them: it is unknown how to make the model conform to the metamodel.
-   This might be because there is no possible relation, or just because there is no relation defined yet.
+     >>>
+
+.. exception:: GroupPermissionDenied : PermissionDenied
 
    Examples:
 
-   * When erroneously trying to interpret a petrinet model as a Class Diagram.
-   
-     >>> alter_context("models/my_pn", "formalisms/SimpleClassDiagrams")
-     >>> element_list()
-     UnknownMetamodellingHierarchy("models/my_pn")
+   * 
+
+     >>>
+
+.. exception:: AdminPermissionDenied : PermissionDenied
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: InterfaceMismatch : ModelverseException
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: UnknownMetamodellingHierarchy : ModelverseException
+
+   Examples:
+
+   * 
+
+     >>>
+
+.. exception:: NotAnAssociation : ModelverseException
+
+   Examples:
+
+   * 
+
+     >>>
 
 SCCD
 ----

wrappers/classes/modelverse.xml

@@ -1413,13 +1413,6 @@
                         </raise>
                     </transition>
 
-                    <transition cond="self.expect_response_partial('Manual activity needs at least one formalism in its input or output signature', pop=True)" target="../wait_for_action/history">
-                        <raise event="exception">
-                            <parameter expr="'ManualActivityRequiresIO'"/>
-                            <parameter expr="'Manual activities require at least one input or output metamodel to be specified in order to create a meaningful metamodel.'"/>
-                        </raise>
-                    </transition>
-
                     <transition cond="self.expect_response_partial('Source model not bound: ', pop=False)" target="../wait_for_action/history">
                         <raise event="exception">
                             <parameter expr="'SourceModelNotBound'"/>

wrappers/modelverse.py

@@ -66,9 +66,6 @@ class UnknownIdentifier(ModelverseException):
 class CompilationError(ModelverseException):
     pass
 
-class NoSimpleClassDiagramsModel(ModelverseException):
-    pass
-
 class NotAnActivity(ModelverseException):
     pass