Issue 20: Exercise Names + A Refactor to Bring Into Spec Compliance

lib/common/__init__.py

@@ -2,6 +2,6 @@
 Common utilities for analyis of Exercism exercises.
 """
 from .exercise import Exercise, ExerciseError
-from .comment import BaseComments
-from .analysis import Analysis, Status
+from .comment import BaseFeedback, Summary
+from .analysis import Analysis
 from .testing import BaseExerciseTest

lib/common/analysis.py

@@ -4,28 +4,9 @@
 
 import json
 from pathlib import Path
-from enum import Enum, auto, unique
-from typing import List
-
-Comments = List[Enum]
-PylintComments = List[str]
-
-
-@unique
-class Status(Enum):
-    """
-    Status of the exercise under analysis.
-    """
-
-    APPROVE = auto()
-    DISAPPROVE = auto()
-    REFER_TO_MENTOR = auto()
-
-    def __str__(self):
-        return self.name.lower()
-
-    def __repr__(self):
-        return f"{self.__class__.__name__}.{self.name}"
+from enum import Enum
+from dataclasses import asdict, is_dataclass
+from common.comment import Summary
 
 
 class AnalysisEncoder(json.JSONEncoder):
@@ -36,6 +17,10 @@ class AnalysisEncoder(json.JSONEncoder):
     def default(self, obj):
         if isinstance(obj, Enum):
             return str(obj)
+
+        elif is_dataclass(obj):
+            return asdict(obj)
+
         return json.JSONEncoder.default(self, obj)
 
 
@@ -44,67 +29,52 @@ class Analysis(dict):
     Represents the current state of the analysis of an exercise.
     """
 
-    def __init__(self, status, comment, pylint_comment, approvable=False):
-        super(Analysis, self).__init__(
-            status=status, comment=comment, pylint_comment=pylint_comment
-        )
-        self._approvable = approvable
+    def __init__(self, summary, comments):
+        super(Analysis, self).__init__(summary=summary, comments=comments)
 
-    @property
-    def status(self) -> Status:
-        """
-        The current status of the analysis.
-        """
-        return self["status"]
 
     @property
-    def comment(self) -> Comments:
+    def summary(self) -> Summary:
         """
-        The list of comments for the analysis.
+        The current summary of the analysis.
         """
-        return self["comment"]
 
-    @property
-    def pylint_comment(self) -> PylintComments:
-        """
-        The list of pylint comments for the analysis.
-        """
-        return self["pylint_comment"]
+        return self["summary"]
 
     @property
-    def approvable(self):
+    def comment(self):
         """
-        Is this analysis _considered_ approvable?
-        Note that this does not imply an approved status, but that the exercise
-        has hit sufficient points that a live Mentor would likely approve it.
+        The list of comments for the analysis.
         """
-        return self._approvable
+        return self["comments"]
 
     @classmethod
-    def approve(cls, comment=None, pylint_comment=None):
+    def celebrate(cls,  comments=None):
         """
         Create an Anaylsis that is approved.
         If non-optimal, comment should be a list of Comments.
         """
-        return cls(
-            Status.APPROVE, comment or [], pylint_comment or [], approvable=True
-        )
+        return cls(Summary.CELEBRATE, comments or [])
+
 
     @classmethod
-    def disapprove(cls, comment, pylint_comment=None):
+    def require(cls, comments):
         """
         Create an Analysis that is disapproved.
         """
-        return cls(Status.DISAPPROVE, comment, pylint_comment or [])
+        return cls(Summary.REQUIRE, comments)
 
     @classmethod
-    def refer_to_mentor(cls, comment, pylint_comment=None, approvable=False):
+    def direct(cls, comments):
         """
         Create an Analysis that should be referred to a mentor.
         """
-        return cls(
-            Status.REFER_TO_MENTOR, comment, pylint_comment or [], approvable=approvable
-        )
+        return cls(Summary.DIRECT, comments)
+
+    @classmethod
+    def inform(cls, comments, pylint_comment=None):
+        return cls(Summary.INFORM, comments)
+
 
     def dump(self, out_path: Path):
         """

lib/common/comment.py

@@ -1,13 +1,15 @@
 """
-Classes for working with comments.
+Classes for working with comments and comment types.
 """
 from enum import Enum, unique
+from dataclasses import dataclass, field, asdict
+
 
 
 @unique
-class BaseComments(Enum):
+class BaseFeedback(Enum):
     """
-    Superclass for all analyzers to user to build their Comments.
+    Superclass for all analyzers to user to build their Feedback.
     """
 
     def __new__(cls, namespace, comment):
@@ -20,3 +22,50 @@ def __str__(self):
 
     def __repr__(self):
         return f"{self.__class__.__name__}.{self.name}"
+
+
+
+@unique
+class CommentTypes(Enum):
+    """
+    Superclass for all analyzers to us for comment types
+    """
+
+    CELEBRATORY = 'celebratory'
+    ESSENTIAL = 'essential'
+    ACTIONABLE = 'actionable'
+    INFORMATIVE = 'informative'
+
+    def __str__(self):
+        return self.value.lower()
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+@dataclass
+class Comment:
+    comment: str = None
+    params: dict = field(default_factory=dict)
+    type:   Enum = CommentTypes.INFORMATIVE
+
+
+
+
+@unique
+class Summary(Enum):
+    """
+    Summary of the comments for the exercise under analysis.
+    """
+
+    CELEBRATE = "Congratulations!  This solution is very close to ideal!  We don't have any specific recommendations."
+    REQUIRE = "There are a few changes we'd like you to make before completing this exercise."
+    DIRECT = "There are a few changes we suggest that can bring your solution closer to ideal."
+    INFORM = "Good work!  Here are some general recommendations for improving your Python code."
+    GENERIC = "We don't have a custom analysis for thsi exercise yet, but here are some comments from PyLint to help you improve your code."
+
+    def __str__(self):
+        return self.value.lower()
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"

lib/common/exercise.py

@@ -3,6 +3,7 @@
 """
 import sys
 import importlib
+import json
 from pathlib import Path
 from typing import NamedTuple
 
@@ -24,7 +25,7 @@ class Exercise(NamedTuple):
     Manages analysis of a an individual Exercise.
     """
 
-    name: str
+    slug: str
     in_path: Path
     out_path: Path
     tests_path: Path
@@ -34,9 +35,10 @@ def analyzer(self):
         """
         The analyzer.py module for this Exercise, imported lazily.
         """
-        module_name = f"{Exercise.sanitize_name(self.name)}_analyzer"
+        module_name = f"{Exercise.sanitize_name(self.slug)}_analyzer"
+
         if module_name not in sys.modules:
-            module = self.available_analyzers()[self.name]
+            module = self.available_analyzers()[self.slug]
             spec = importlib.util.spec_from_file_location(module_name, module)
             analyzer = importlib.util.module_from_spec(spec)
             spec.loader.exec_module(analyzer)
@@ -57,11 +59,11 @@ def analyze(self):
         return self.analyzer.analyze(self.in_path, self.out_path)
 
     @staticmethod
-    def sanitize_name(name: str) -> str:
+    def sanitize_name(slug: str) -> str:
         """
         Sanitize an Exercise name (ie "two-fer" -> "two_fer").
         """
-        return name.replace("-", "_")
+        return slug.replace("-", "_")
 
     @classmethod
     def available_analyzers(cls):
@@ -71,15 +73,31 @@ def available_analyzers(cls):
         return ANALYZERS
 
     @classmethod
-    def factory(cls, name: str, in_directory: Path, out_directory: Path) -> "Exercise":
+    def factory(cls, slug: str, in_directory: Path, out_directory: Path) -> "Exercise":
         """
         Build an Exercise from its name and the directory where its files exist.
         """
-        if name not in cls.available_analyzers():
-            path = LIBRARY.joinpath(name, "analyzer.py")
+
+        if slug not in cls.available_analyzers():
+            path = LIBRARY.joinpath(slug, "analyzer.py")
             raise ExerciseError(f"No analyzer discovered at {path}")
-        sanitized = cls.sanitize_name(name)
-        in_path = in_directory.joinpath(f"{sanitized}.py").resolve()
-        out_path = out_directory.joinpath(f"{sanitized}.py").resolve()
-        tests_path = in_directory.joinpath(f"{sanitized}_test.py").resolve()
-        return cls(name, in_path, out_path, tests_path)
+
+        in_path = None
+        out_path = None
+        tests_path = None
+
+        config_file = in_directory.joinpath(".meta").joinpath("config.json")
+
+        if config_file.is_file():
+            config_data = json.loads(config_file.read_text())
+            in_path = in_directory.joinpath(config_data.get('files', {}).get('solution')[0])
+            out_path = out_directory.joinpath(config_data.get('files', {}).get('solution')[0])
+            tests_path = in_directory.joinpath(config_data.get('files', {}).get('test')[0])
+
+        else:
+            sanitized = cls.sanitize_name(slug)
+            in_path = in_directory.joinpath(f"{sanitized}.py").resolve()
+            out_path = out_directory.joinpath(f"{sanitized}.py").resolve()
+            tests_path = in_directory.joinpath(f"{sanitized}_test.py").resolve()
+
+        return cls(slug, in_path, out_path, tests_path)

lib/common/pylint_comments.py

@@ -0,0 +1,39 @@
+from common.comment import Comment, CommentTypes
+from pylint import epylint as lint
+from pathlib import Path
+
+
+def generate_pylint_comments(in_path):
+    '''
+        Use Pylint to generate additional feedback comments for code,
+
+        e.g. if code follows PEP8 Style Convention
+    '''
+
+    pylint_stdout, _ = lint.py_run(
+        str(in_path) + ' --score=no --msg-template="{category}, {line}, {msg_id} {symbol}, {msg}"',
+        return_std=True
+    )
+
+    status_mapping = {
+        'informational': CommentTypes.INFORMATIVE,
+        'refactor' :  CommentTypes.ACTIONABLE,
+        'convention' : CommentTypes.ACTIONABLE,
+        'warning' : CommentTypes.ESSENTIAL,
+        'error' : CommentTypes.ESSENTIAL,
+        'fatal' : CommentTypes.ESSENTIAL
+    }
+
+    cleaned_pylint_output = [tuple(item.strip('" ').split(', '))
+                             for item in pylint_stdout.getvalue().splitlines()
+                             if '**' not in item]
+
+    pylint_comments = []
+
+    for line in cleaned_pylint_output:
+        if line[0]:
+            pylint_comments.append(Comment(type=status_mapping[line[0]],
+                                           params={'lineno': line[1], 'code': line[2], 'message': line[3]},
+                                           comment=f'python.pylint.{line[0]}'))
+
+    return pylint_comments

lib/common/testing.py

@@ -6,13 +6,13 @@
 from tempfile import TemporaryDirectory
 from typing import Optional
 from .exercise import Exercise
-from .analysis import Status
+from .comment import Summary
 
 
 class BaseExerciseTest(ABC):
     @property
     @abstractmethod
-    def name(self) -> str:
+    def slug(self) -> str:
         """
         The name of the exercise under test (ie `two-fer`)
         """
@@ -37,7 +37,7 @@ def setUp(self):
         Basic test setup.
         """
         self.exercise = Exercise.factory(
-            self.name, Path(self.root.name).resolve(strict=True)
+            self.slug, Path(self.root.name).resolve(strict=True)
         )
         self.analyzer = self.exercise.analyzer
         self.comments = self.exercise.comments
@@ -77,9 +77,8 @@ def test_no_module(self):
         Ensure the analyzer can handle a missing module.
         """
         analysis = self.get_analysis(None)
-        self.assertIs(analysis.status, Status.DISAPPROVE)
+        self.assertIs(analysis.status, Summary.REQUIRE)
         self.assertIn(self.comments.NO_MODULE, analysis.comment)
-        self.assertIs(analysis.approvable, False)
 
     def test_has_module(self):
         """
@@ -93,9 +92,8 @@ def test_has_malformed_code(self):
         Ensure the analyzer can handle malformed code.
         """
         analysis = self.get_analysis("fed test();")
-        self.assertIs(analysis.status, Status.DISAPPROVE)
+        self.assertIs(analysis.status, Summary.REQUIRE)
         self.assertIn(self.comments.MALFORMED_CODE, analysis.comment)
-        self.assertIs(analysis.approvable, False)
 
     def test_no_malformed_code(self):
         """