feat: add class ProficencyScore

Author: chriswblake

openproficiency/ProficiencyScore.py

@@ -0,0 +1,98 @@
+"""ProficiencyScore module for OpenProficiency library."""
+
+from enum import Enum
+from typing import Union
+
+
+class ProficiencyScoreName(Enum):
+    """Enum for proficiency score names."""
+    UNAWARE = 0.0
+    AWARE = 0.1
+    FAMILIAR = 0.5
+    PROFICIENT = 0.8
+    PROFICIENT_WITH_EVIDENCE = 1.0
+
+
+class ProficiencyScore:
+    """Class representing a proficiency score for a topic."""
+
+    # Initializers
+    def __init__(
+        self,
+        # Required
+        topic_id: str,
+        score: Union[float, ProficiencyScoreName]
+    ):
+        # Required
+        self.topic_id = topic_id
+        self._set_score(score)
+
+    # Properties - Score
+    @property
+    def score(self) -> float:
+        """Get the score as a numeric value between 0.0 and 1.0."""
+        return self._score
+
+    @score.setter
+    def score(self, value: Union[float, ProficiencyScoreName]) -> None:
+        """Set the score numerically or using a ProficiencyScoreName enum."""
+        self._set_score(value)
+
+    # Properties - Score
+    @property
+    def score_name(self) -> ProficiencyScoreName:
+        """Get the proficiency name as an enum value."""
+        return self._get_name_from_score(self._score)
+
+    @score_name.setter
+    def score_name(self, value: ProficiencyScoreName) -> None:
+        """Set the proficiency name using a ProficiencyScoreName enum."""
+        if not isinstance(value, ProficiencyScoreName):
+            raise ValueError(
+                f"Name must be a ProficiencyScoreName enum, got {type(value)}")
+        self._score = value.value
+
+    # Methods
+    def _set_score(self, value: Union[float, ProficiencyScoreName]) -> None:
+        """Internal method to set score from numeric or enum value."""
+        if isinstance(value, ProficiencyScoreName):
+            self._score = value.value
+
+        elif isinstance(value, (int, float)):
+            # Validate score is between 0.0 and 1.0
+            if not (0.0 <= value <= 1.0):
+                raise ValueError(
+                    f"Score must be between 0.0 and 1.0, got {value}")
+            self._score = float(value)
+
+        else:
+            raise ValueError(
+                f"Score must be numeric or ProficiencyScoreName enum. Got type: '{type(value)}'")
+
+    def _get_name_from_score(self, score: float) -> ProficiencyScoreName:
+        """Internal method to determine proficiency name from numeric score."""
+        if score <= 0.0:
+            return ProficiencyScoreName.UNAWARE
+        elif score <= 0.1:
+            return ProficiencyScoreName.AWARE
+        elif score <= 0.5:
+            return ProficiencyScoreName.FAMILIAR
+        elif score <= 0.8:
+            return ProficiencyScoreName.PROFICIENT
+        elif score <= 1.0:
+            return ProficiencyScoreName.PROFICIENT_WITH_EVIDENCE
+        else:
+            raise ValueError(f"Invalid score value: {score}")
+
+    def to_json(self) -> dict:
+        """Convert to a JSON-serializable dictionary."""
+        return {
+            "topic_id": self.topic_id,
+            "score": self._score
+        }
+
+    # Debugging
+
+    def __repr__(self) -> str:
+        """String representation of ProficiencyScore."""
+        return f"ProficiencyScore(topic_id='{self.topic_id}', score={self._score}, name={self.score_name.name})"

openproficiency/__init__.py

@@ -1,4 +1,5 @@
 """OpenProficiency - Library to manage proficiency scores using topics and topic lists."""
 
 from .Topic import Topic
-from .TopicList import TopicList
+from .TopicList import TopicList
+from .ProficiencyScore import ProficiencyScore, ProficiencyScoreName

tests/ProficiencyScore_test.py

@@ -0,0 +1,218 @@
+"""Tests for the ProficiencyScore class."""
+
+from openproficiency import ProficiencyScore, ProficiencyScoreName
+
+
+class TestProficiencyScore:
+
+    # Initializers
+    def test_init_with_numeric_score(self):
+        """Create a proficiency score with numeric value."""
+
+        # Arrange
+        topic_id = "git-commit"
+        score = 0.8
+
+        # Act
+        ps = ProficiencyScore(topic_id=topic_id, score=score)
+
+        # Assert
+        assert ps.topic_id == topic_id
+        assert ps.score == score
+
+    def test_init_with_enum_score(self):
+        """Create a proficiency score with ProficiencyScoreName enum."""
+
+        # Arrange
+        topic_id = "git-commit"
+        score_name = ProficiencyScoreName.PROFICIENT
+
+        # Act
+        ps = ProficiencyScore(topic_id=topic_id, score=score_name)
+
+        # Assert
+        assert ps.topic_id == topic_id
+        assert ps.score == 0.8
+
+    def test_init_invalid_score_too_low(self):
+        """Test that score below 0.0 raises ValueError."""
+
+        # Act & Assert
+        try:
+            ProficiencyScore(topic_id="test", score=-0.1)
+            assert False, "Should have raised ValueError"
+        except ValueError as e:
+            assert "between 0.0 and 1.0" in str(e)
+
+    def test_init_invalid_score_too_high(self):
+        """Test that score above 1.0 raises ValueError."""
+
+        # Act & Assert
+        try:
+            ProficiencyScore(topic_id="test", score=1.1)
+            assert False, "Should have raised ValueError"
+        except ValueError as e:
+            assert "between 0.0 and 1.0" in str(e)
+
+    def test_init_invalid_score_type(self):
+        """Test that invalid score type raises ValueError."""
+
+        # Act & Assert
+        try:
+            ProficiencyScore(topic_id="test", score="invalid")
+            assert False, "Should have raised ValueError"
+        except ValueError as e:
+            assert "numeric or ProficiencyScoreName" in str(e)
+
+    # Properties - Score
+    def test_score_getter(self):
+        """Test getting score property."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.5)
+
+        # Act & Assert
+        assert ps.score == 0.5
+
+    def test_score_setter_numeric(self):
+        """Test setting score with numeric value."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.1)
+
+        # Act
+        ps.score = 0.9
+
+        # Assert
+        assert ps.score == 0.9
+
+    def test_score_setter_enum(self):
+        """Test setting score with enum value."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.1)
+
+        # Act
+        ps.score = ProficiencyScoreName.FAMILIAR
+
+        # Assert
+        assert ps.score == 0.5
+
+    def test_score_setter_invalid(self):
+        """Test setting invalid score raises ValueError."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.1)
+
+        # Act & Assert
+        try:
+            ps.score = 1.5
+            assert False, "Should have raised ValueError"
+        except ValueError:
+            pass
+
+    # Properties - Score Name
+    def test_score_name_unaware(self):
+        """Test score_name property for UNAWARE level."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.0)
+
+        # Act & Assert
+        assert ps.score_name == ProficiencyScoreName.UNAWARE
+
+    def test_score_name_aware(self):
+        """Test score_name property for AWARE level."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.05)
+
+        # Act & Assert
+        assert ps.score_name == ProficiencyScoreName.AWARE
+
+    def test_score_name_familiar(self):
+        """Test score_name property for FAMILIAR level."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.3)
+
+        # Act & Assert
+        assert ps.score_name == ProficiencyScoreName.FAMILIAR
+
+    def test_score_name_proficient(self):
+        """Test score_name property for PROFICIENT level."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.8)
+
+        # Act & Assert
+        assert ps.score_name == ProficiencyScoreName.PROFICIENT
+
+    def test_score_name_proficient_with_evidence(self):
+        """Test score_name property for PROFICIENT_WITH_EVIDENCE level."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=1.0)
+
+        # Act & Assert
+        assert ps.score_name == ProficiencyScoreName.PROFICIENT_WITH_EVIDENCE
+
+    def test_score_name_setter(self):
+        """Test setting score_name property."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.1)
+
+        # Act
+        ps.score_name = ProficiencyScoreName.PROFICIENT
+
+        # Assert
+        assert ps.score == 0.8
+
+    def test_score_name_setter_invalid_type(self):
+        """Test setting score_name with invalid type raises ValueError."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="test", score=0.1)
+
+        # Act & Assert
+        try:
+            ps.score_name = 0.5
+            assert False, "Should have raised ValueError"
+        except ValueError as e:
+            assert "ProficiencyScoreName enum" in str(e)
+
+    # Methods
+
+    def test_to_json(self):
+        """Test conversion to JSON-serializable dictionary."""
+
+        # Arrange
+        topic_id = "git-commit"
+        score = 0.8
+        ps = ProficiencyScore(topic_id=topic_id, score=score)
+
+        # Act
+        json_dict = ps.to_json()
+
+        # Assert
+        assert json_dict == {
+            "topic_id": topic_id,
+            "score": score
+        }
+
+    # Debugging
+    def test_repr(self):
+        """Test string representation of ProficiencyScore."""
+
+        # Arrange
+        ps = ProficiencyScore(topic_id="git-commit", score=0.8)
+
+        # Act
+        repr_str = repr(ps)
+
+        # Assert
+        assert "ProficiencyScore" in repr_str
+        assert "git-commit" in repr_str
+        assert "0.8" in repr_str
+        assert "PROFICIENT" in repr_str