Merge 9e58fea into 965bbd2

praw/models/reddit/flair.py

@@ -0,0 +1,67 @@
+"""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.
+
+    It has the same typical values as :class:`.SubmissionFlair`.
+    """
+
+    def change_css_class(self, css_class):
+        """Change the css class of the flair (Mod only)."""
+        self.flair_css_class = css_class

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
         )