Merge 7292ea0 into 965bbd2

praw/models/__init__.py

@@ -12,6 +12,7 @@
 from .preferences import Preferences
 from .reddit.collections import Collection
 from .reddit.comment import Comment
+from .reddit.flair import SubmissionFlair, SubmissionModerationFlair
 from .reddit.emoji import Emoji
 from .reddit.live import LiveThread, LiveUpdate
 from .reddit.message import Message, SubredditMessage

praw/models/reddit/flair.py

@@ -0,0 +1,88 @@
+"""Provide the Flair class."""
+from .base import RedditBase
+
+
+class SubmissionFlair(RedditBase):
+    """An individual SubmissionFlair object.
+
+    **Typical Attributes**
+
+    This table describes attributes that typically belong to objects of this
+    class. Since attributes are dynamically provided (see
+    :ref:`determine-available-attributes-of-an-object`), there is not a
+    guarantee that these attributes will always be present, nor is this list
+    necessarily comprehensive.
+
+    ======================= ===================================================
+    Attribute               Description
+    ======================= ===================================================
+    ``flair_template_id``   The id of the flair template.
+    ``flair_text_editable`` Whether or not the flair text can be edited.
+    ``flair_text``          The text of the flair
+    """
+
+    STR_FIELD = "flair_text"
+
+    def __eq__(self, other):
+        """Check that two flairs are the same flair."""
+        if isinstance(other, str):
+            return str(self) == other
+        return (
+            isinstance(other, self.__class__)
+            and str(self) == str(other)
+            and self.flair_template_id == other.flair_template_id
+        )
+
+    def __hash__(self):
+        """Return the hash of the flair."""
+        return (
+            hash(self.__class__.__name__)
+            ^ hash(str(self))
+            ^ hash(self.flair_template_id)
+            ^ hash(self.submission)
+        )
+
+    def __init__(self, reddit, submission, _data):
+        """Instantizes the flair object."""
+        self.submission = submission
+        super().__init__(reddit, _data=_data)
+
+    def change_text(self, text):
+        """Allow the submission author to give a custom text to the flair.
+
+        Please verify that the flair is editable before editing the text of the
+        flair.
+        """
+        self.flair_text = text
+
+
+class SubmissionModerationFlair(SubmissionFlair):
+    """A special flair that is returned to moderators.
+
+    **Typical Attributes**
+
+    This table describes attributes that typically belong to objects of this
+    class. Since attributes are dynamically provided (see
+    :ref:`determine-available-attributes-of-an-object`), there is not a
+    guarantee that these attributes will always be present, nor is this list
+    necessarily comprehensive.
+
+    ======================= ===================================================
+    Attribute               Description
+    ======================= ===================================================
+    ``text``                The text of the flair
+    ``max_emojis``          The amount of :class:`.Emoji` that can go in the
+                            flair.
+    ``mod_only``            Whether or not the flair is mod only or not.
+    ``css_class``           The css class of the flair.
+    ``background_color``    The background color of the flair
+    ``id``                  The flair template id
+    """
+
+    def change_css_class(self, css_class):
+        """Change the css class of the flair (Mod only)."""
+        self.css_class = css_class
+
+    def change_text(self, text):
+        """Change the text of the flair (Mod only)"""
+        self.text = text

praw/models/reddit/submission.py

@@ -396,31 +396,46 @@ def choices(self):
             url, data={"link": self.submission.fullname}
         )["choices"]
 
-    def select(self, flair_template_id, text=None):
+    def select(self, template_id=None, text=None, flair=None):
         """Select flair for submission.
 
-        :param flair_template_id: The flair template to select. The possible
-            ``flair_template_id`` values can be discovered through
-            :meth:`.choices`.
-        :param text: If the template's ``flair_text_editable`` value is True,
-            this value will set a custom text (default: None).
+        :param template_id: The template id of the flair to apply.
+        :param text: The custom text to add to the flair
+        :param flair: The instance of :class:`.SubmissionFlair` to use.
+
+        The template_id and flair paramater are mutually exclusive.
+
+        If there is a text value and a flair value, the text in the flair will
+        be replaced with the text in the text paramater
 
         For example, to select an arbitrary editable flair text (assuming there
         is one) and set a custom value try:
 
         .. code:: python
 
            choices = submission.flair.choices()
-           template_id = next(x for x in choices
-                              if x['flair_text_editable'])['flair_template_id']
-           submission.flair.select(template_id, 'my custom value')
+           flair = next(x for x in choices
+                              if x.flair_text_editable)
+           flair.change_text("custom value")
+           submission.flair.select(flair)
 
         """
-        data = {
-            "flair_template_id": flair_template_id,
-            "link": self.submission.fullname,
-            "text": text,
-        }
+        if [template_id, flair].count(None) != 1:
+            raise TypeError("Either template_id or flair should be given.")
+        if flair is not None:
+            if text is not None:
+                flair.change_text(text)
+            data = {
+                "flair_template_id": flair.flair_template_id,
+                "link": self.submission.fullname,
+                "text": flair.flair_text,
+            }
+        else:
+            data = {
+                "flair_template_id": template_id,
+                "link": self.submission.fullname,
+                "text": text,
+            }
         url = API_PATH["select_flair"].format(
             subreddit=self.submission.subreddit
         )

tests/unit/models/reddit/test_flair.py

@@ -0,0 +1,168 @@
+from praw.models import Submission, SubmissionFlair, SubmissionModerationFlair
+
+from ... import UnitTest
+
+
+class TestFlair(UnitTest):
+    def test_attrs(self):
+        example = {
+            "flair_css_class": "Test",
+            "flair_template_id": "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d",
+            "flair_text_editable": True,
+            "flair_position": "right",
+            "flair_text": "Test",
+        }
+        example_submission = Submission(self.reddit, id="dummy")
+        example_flair = SubmissionFlair(
+            self.reddit, example_submission, example
+        )
+        assert example_flair.flair_css_class == "Test"
+        assert (
+            example_flair.flair_template_id
+            == "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d"
+        )
+        assert example_flair.flair_text_editable
+        assert example_flair.flair_position == "right"
+        assert example_flair.flair_text == "Test"
+
+    def test_change(self):
+        example = {
+            "flair_css_class": "Test",
+            "flair_template_id": "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d",
+            "flair_text_editable": True,
+            "flair_position": "right",
+            "flair_text": "Test",
+        }
+        example_submission = Submission(self.reddit, id="dummy")
+        example_flair = SubmissionFlair(
+            self.reddit, example_submission, example
+        )
+        assert example_flair.flair_text == "Test"
+        example_flair.change_text("Testing")
+        assert example_flair.flair_text == "Testing"
+
+    def test_equality(self):
+        example = {
+            "flair_css_class": "Test",
+            "flair_template_id": "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d",
+            "flair_text_editable": True,
+            "flair_position": "right",
+            "flair_text": "Test",
+        }
+        example_submission = Submission(self.reddit, id="dummy")
+        example_flair = SubmissionFlair(
+            self.reddit, example_submission, example
+        )
+        example_flair_2 = SubmissionFlair(
+            self.reddit, example_submission, example
+        )
+        assert example_flair == example_flair_2
+        assert hash(example_flair) == hash(example_flair_2)
+        example_flair.change_text("Testt")
+        assert example_flair != example_flair_2
+        assert hash(example_flair) != hash(example_flair_2)
+
+
+class TestFlairMod(UnitTest):
+    def test_attrs(self):
+        example = {
+            "type": "text",
+            "text_editable": False,
+            "allowable_content": "all",
+            "text": "Test",
+            "max_emojis": 10,
+            "text_color": "dark",
+            "mod_only": False,
+            "css_class": "Test",
+            "richtext": [],
+            "background_color": "",
+            "id": "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d",
+        }
+        example_submission = Submission(self.reddit, id="dummy")
+        example_flair = SubmissionModerationFlair(
+            self.reddit, example_submission, example
+        )
+        assert example_flair.type == "text"
+        assert not example_flair.text_editable
+        assert example_flair.allowable_content == "all"
+        assert example_flair.text == "Test"
+        assert example_flair.max_emojis == 10
+        assert example_flair.text_color == "dark"
+        assert not example_flair.mod_only
+        assert example_flair.css_class == "Test"
+        assert example_flair.richtext == []
+        assert len(example_flair.richtext) == 0
+        assert example_flair.background_color == ""
+        assert len(example_flair.background_color) == 0
+        assert example_flair.id == "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d"
+
+    def test_changes(self):
+        example = {
+            "type": "text",
+            "text_editable": False,
+            "allowable_content": "all",
+            "text": "Test",
+            "max_emojis": 10,
+            "text_color": "dark",
+            "mod_only": False,
+            "css_class": "Test",
+            "richtext": [],
+            "background_color": "",
+            "id": "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d",
+        }
+        example_submission = Submission(self.reddit, id="dummy")
+        example_flair = SubmissionModerationFlair(
+            self.reddit, example_submission, example
+        )
+        assert example_flair.text == "Test"
+        example_flair.change_text("Testing")
+        assert example_flair.text == "Testing"
+        assert example_flair.css_class == "Test"
+        example_flair.change_css_class("Testing")
+        assert example_flair.css_class == "Testing"
+
+    def test_equality(self):
+        example = {
+            "type": "text",
+            "text_editable": False,
+            "allowable_content": "all",
+            "text": "Test",
+            "max_emojis": 10,
+            "text_color": "dark",
+            "mod_only": False,
+            "css_class": "Test",
+            "richtext": [],
+            "background_color": "",
+            "id": "0f7349d8-2a6d-11ea-8529-0e5dee3e1a9d",
+        }
+        example_submission = Submission(self.reddit, id="dummy")
+        example_flair = SubmissionModerationFlair(
+            self.reddit, example_submission, example
+        )
+        example_flair_2 = SubmissionModerationFlair(
+            self.reddit, example_submission, example
+        )
+        example_flair_3 = SubmissionModerationFlair(
+            self.reddit, example_submission, example
+        )
+        assert example_flair == example_flair_2 == example_flair_3
+        assert (
+            hash(example_flair)
+            == hash(example_flair_2)
+            == hash(example_flair_3)
+        )
+        example_flair.change_text("T")
+        assert (
+            example_flair != example_flair_2
+            and example_flair != example_flair_3
+        )
+        assert hash(example_flair) != hash(example_flair_2) and hash(
+            example_flair
+        ) != hash(example_flair_3)
+        assert example_flair_2 == example_flair_3
+        assert hash(example_flair_2) == hash(example_flair_3)
+        example_flair_2.change_css_class("DSF")
+        assert example_flair != example_flair_2
+        assert example_flair_2 != example_flair_3
+        assert hash(example_flair) != hash(example_flair_2)
+        assert hash(example_flair_2) != hash(example_flair_3)