Merge f468a0f into e5a57bd

praw/models/__init__.py

@@ -12,6 +12,11 @@
 from .preferences import Preferences
 from .reddit.collections import Collection
 from .reddit.comment import Comment
+from .reddit.flair import (
+    SubmissionFlair,
+    SubmissionModerationFlair,
+    RedditorFlair,
+)
 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,165 @@
+"""Provide the Flair class."""
+from .base import RedditBase
+
+
+class RichFlairBase(RedditBase):
+    """A base class for rich flairs.
+
+    Flairs of this type are obtained by either
+    :meth:`.SubredditFlair.templates`
+    or :meth:`.SubredditFlair.link_templates`.
+    """
+
+    STR_FIELD = "text"
+
+    def __eq__(self, other):
+        """Check that two instances of the class are equal."""
+        if isinstance(other, str):
+            return str(self) == other
+        return (
+            isinstance(other, self.__class__)
+            and str(self) == str(other)
+            and self.id == other.id
+            and self.css_class == other.css_class
+        )
+
+    def __hash__(self):
+        """Get the hash of the instance."""
+        return (
+            hash(self.__class__.__name__)
+            ^ hash(str(self))
+            ^ hash(self.id)
+            ^ hash(self.css_class)
+        )
+
+    def __init__(self, reddit, _data):
+        """Initialize the class."""
+        super().__init__(reddit, _data=_data)
+
+    def change_css_class(self, css_class):
+        """Change the css class of the flair."""
+        self.css_class = css_class
+
+    def change_text(self, text):
+        """Change the text of the flair."""
+        self.text = text
+
+
+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)
+        )
+
+    def __init__(self, reddit, _data):
+        """Instantizes the flair object."""
+        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(RichFlairBase):
+    """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
+    ======================= ===================================================
+    ``allowable_content``   The type of content allowed in the flair (
+                            acceptable values are ``all``, ``emoji`` or
+                            ``text``).
+    ``background_color``    The background color of the flair. Values can be a
+                            color name (``dark`` or a 6-digit RGB code
+                            ``#ffffff``.)
+    ``css_class``           The css class of the flair.
+    ``id``                  The flair template id.
+    ``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.
+    ``richtext``            A list containing data about any richtext elements,
+                            including any emojis, present in the flair.
+    ``text``                The text of the flair.
+    ``text_color``          The color of the text
+    ``text_editable``       Whether or not the flair text can be edited.
+    ``type``                The type of the flair (``text`` or ``richtext``.)
+    """
+
+
+class RedditorFlair(RichFlairBase):
+    """An individual RedditorFlair 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
+    ======================= ===================================================
+    ``allowable_content``   The type of content allowed in the flair (
+                            acceptable values are ``all``, ``emoji`` or
+                            ``text``).
+    ``background_color``    The background color of the flair. Values can be a
+                            color name (``dark`` or a 6-digit RGB code
+                            ``#ffffff``.)
+    ``css_class``           The css class of the flair.
+    ``id``                  The flair template id.
+    ``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.
+    ``richtext``            A list containing data about any richtext elements,
+                            including any emojis, present in the flair.
+    ``text``                The text of the flair.
+    ``text_color``          The color of the text
+    ``text_editable``       Whether or not the flair text can be edited.
+    ``type``                The type of the flair (``text`` or ``richtext``.)
+    """

praw/models/reddit/submission.py

@@ -14,6 +14,7 @@
 from .subreddit import Subreddit
 
 _Submission = TypeVar("_Submission")
+Flair = TypeVar("Flair)")
 Reddit = TypeVar("Reddit")
 
 
@@ -47,31 +48,51 @@ def choices(self) -> List[Dict[str, Union[bool, list, str]]]:
             url, data={"link": self.submission.fullname}
         )["choices"]
 
-    def select(self, flair_template_id: str, text: Optional[str] = None):
+    def select(
+        self,
+        template_id: Optional[str] = None,
+        text: Optional[str] = None,
+        flair: Optional[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
         )