diff --git a/praw/models/reddit/flair.py b/praw/models/reddit/flair.py new file mode 100644 index 0000000000..c0f6f08a81 --- /dev/null +++ b/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 diff --git a/praw/models/reddit/submission.py b/praw/models/reddit/submission.py index 759c234bf0..ab26eebb1c 100644 --- a/praw/models/reddit/submission.py +++ b/praw/models/reddit/submission.py @@ -396,14 +396,17 @@ 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: @@ -411,16 +414,28 @@ def select(self, flair_template_id, text=None): .. 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 )