Document and provide example for announcement_client (#462)

* example_for_announcements_client | 🎉 Initial commit.

* example_for_announcements_client | 🚨 Removing linter warnings.

* example_for_announcements_client | 🚚 Moving or renaming variables.

* example_for_announcements_client | ♻ Refactoring code.

amundsen_application/base/examples/example_announcement_client.py

+from random import randint
+from datetime import datetime, timedelta
+
+from amundsen_application.models.announcements import Announcements, Post
+from amundsen_application.base.base_announcement_client import BaseAnnouncementClient
+
+try:
+    from sqlalchemy import Column, Integer, String, DateTime, create_engine
+    from sqlalchemy.ext.declarative import declarative_base
+    from sqlalchemy.orm import sessionmaker
+except ModuleNotFoundError:
+    pass
+
+Base = declarative_base()
+
+
+class DBAnnouncement(Base):  # type: ignore
+    __tablename__ = 'announcements'
+
+    id = Column(Integer, primary_key=True)
+
+    date = Column(DateTime)
+    title = Column(String)
+    content = Column(String)
+
+
+class SQLAlchemyAnnouncementClient(BaseAnnouncementClient):
+    def __init__(self) -> None:
+        self._setup_mysql()
+
+    def _setup_mysql(self) -> None:
+        self.engine = create_engine('sqlite:////tmp/amundsen.db', echo=True)
+
+        session = sessionmaker(bind=self.engine)()
+
+        # add dummy announcements to preview
+        if not self.engine.dialect.has_table(self.engine, DBAnnouncement.__tablename__):
+            Base.metadata.create_all(self.engine)
+
+            announcements = []
+
+            dummy_announcement = """
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at dapibus lorem.
+            Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.
+            Suspendisse est lectus, bibendum vitae vestibulum vitae, commodo eu tortor.
+            Sed rhoncus augue eget turpis interdum, eu aliquam lectus ornare. Aenean tempus in mauris vitae viverra.
+            """
+
+            for i in range(randint(5, 9)):
+                announcement = DBAnnouncement(id=i + 1,
+                                              date=datetime.now() + timedelta(days=i + 1),
+                                              title=f'Test announcement title {i + 1}',
+                                              content=dummy_announcement)
+
+                announcements.append(announcement)
+
+            session.add_all(announcements)
+            session.commit()
+
+    def get_posts(self) -> Announcements:
+        """
+        Returns an instance of amundsen_application.models.announcements.Announcements, which should match
+        amundsen_application.models.announcements.AnnouncementsSchema
+        """
+        session = sessionmaker(bind=self.engine)()
+
+        posts = []
+
+        for row in session.query(DBAnnouncement).order_by(DBAnnouncement.date.desc()):
+            post = Post(title=row.title,
+                        date=row.date.strftime('%b %d %Y %H:%M:%S'),
+                        html_content=row.content)
+            posts.append(post)
+
+        return Announcements(posts)

docs/configuration.md

@@ -33,12 +33,12 @@ entry_points="""
     table_preview_client_class = amundsen_application.base.examples.example_superset_preview_client:SupersetPreviewClient
 
     [announcement_client]
-    announcement_client_class = path.to.file:CustomAnnouncementClient
+    announcement_client_class = amundsen_application.base.examples.example_announcement_client:SQLAlchemyAnnouncementClient
 """
 ```
 
 ### Action Logging
-Create a custom method to handle action logging. Under the `[action_log.post_exec.plugin]` group, point the `analytic_clients_action_log` entry point in your local `setup.py` to that method.
+Create a custom method to handle action logging. Under the `[ action_log.post_exec.plugin]` group, point the `analytic_clients_action_log` entry point in your local `setup.py` to that method.
 
 ### Preview Client
 Create a custom implementation of [base_preview_client](https://github.com/lyft/amundsenfrontendlibrary/blob/master/amundsen_application/base/base_preview_client.py). Under the `[preview_client]` group, point the `table_preview_client_class` entry point in your local `setup.py` to that class.

docs/examples/announcement_client.md

+# Overview
+
+Amundsen's announcement feature requires that developers create a custom implementation of `announcement_client` for collecting announcements. This feature provide ability to deliver to Users announcements of different sort regarding data discovery service.
+
+## Implementation
+
+Implement the `announcement_client` to make a request to system storing announcements.
+
+### Shared Logic
+[`announcement_client`](https://github.com/lyft/amundsenfrontendlibrary/tree/master/amundsen_application/base/base_announcement_client.py) implements `_get_posts()` of `base_announcement_client` with the minimal logic for this use case.
+
+It collects the posts from `get_posts()` method.
+
+```python
+try:
+    announcements = self.get_posts()
+except Exception as e:
+    message = 'Encountered exception getting posts: ' + str(e)
+    return _create_error_response(message)
+```
+
+It verifies the shape of the data before returning it to the application. If the data does not match the `AnnouncementsSchema`, the request will fail.
+
+```python
+# validate the returned object
+data, errors = AnnouncementsSchema().dump(announcements)
+if not errors:
+    payload = jsonify({'posts': data.get('posts'), 'msg': 'Success'})
+    return make_response(payload, HTTPStatus.OK)
+else:
+    message = 'Announcement data dump returned errors: ' + str(errors)
+    return _create_error_response(message)
+```
+
+### Custom Logic
+`announcement_client` has an abstract method `get_posts()`. 
+
+This method will contain whatever custom logic is needed to collect announcements. The system within which they are stored can be anything that has programmatic access.
+
+Announcements could be collected from database (as in exemplary SQLAlchemyAnnouncementClient), kafka persistent topic, web rss feed, etc.
+
+See the following [`example_announcement_client`](https://github.com/lyft/amundsenfrontendlibrary/tree/master/amundsen_application/base/examples/example_announcement_client.py) for an example implementation of `base_announcement_client` and `get_posts()`. This example assumes a temporary sqlite database with no security, authentication, persistence or authorization configured.
+
+## Usage
+
+Under the `[announcement_client]` group, point the `announcement_client` entry point in your local `setup.py` to your custom class.
+
+```
+entry_points="""
+    ...
+
+    [announcement_client]
+    announcement_client_class = amundsen_application.base.examples.example_announcement_client:SQLAlchemyAnnouncementClient
+"""
+```
+### What do I need to run exemplary announcement_client ?
+
+Exemplary client requires installation of SQLAlchemy to run properly:
+
+```bash
+pip install SQLAlchemy==1.3.17
+```
+
+Run `python3 setup.py install` in your virtual environment and restart the application for the entry point changes to take effect