From 32df4f64d15685f036f40436b57ce1858e8f080e Mon Sep 17 00:00:00 2001 From: rodrigondec Date: Wed, 11 Dec 2019 21:38:18 -0300 Subject: [PATCH 1/4] documentation started --- Makefile | 6 +++++ db/exceptions.py | 6 +++++ db/observer.py | 63 ++++++++++++++++++++++++++++++++++++++++++-- db/subject.py | 37 ++++++++++++++++++++++++-- db/update_message.py | 53 +++++++++++++++++++++++++++++++++++++ requirements-dev.txt | 4 ++- 6 files changed, 164 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 3ddbd17..d92a113 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,12 @@ flake8: pip.install: pip install -r requirements-dev.txt +docs.build: + sphinx-build docs/source/ docs/ + +docs.autodoc: + sphinx-apidoc -f -o docs/source . + ################################# ###### DOCKER DEV COMMANDS ###### ################################# diff --git a/db/exceptions.py b/db/exceptions.py index d3d0f02..a09c49e 100644 --- a/db/exceptions.py +++ b/db/exceptions.py @@ -1,8 +1,14 @@ class ObserverNotRegisteredError(Exception): + """ + Exception responsible for missing Observer registry + """ pass class ObserverAlreadyRegisteredError(Exception): + """ + Exception responsible for duplicated Observer registry + """ pass diff --git a/db/observer.py b/db/observer.py index 2b4037a..073ba8a 100644 --- a/db/observer.py +++ b/db/observer.py @@ -19,6 +19,14 @@ class ObserverMessage(Document): + """MongoDB Document for a observer telegram sent message + + Attributes: + message_id (int): telegram send message id + subject (Subject): subject reference + observer (Observer): observer reference + datetime: now() datetime + """ message_id = IntField(required=True) subject = ReferenceField('Subject', required=True) observer = ReferenceField('Observer', required=True) @@ -36,6 +44,13 @@ def __str__(self): class Observer(Document): + """MongoDB Document for official Telegram Channel + + Attributes: + username (str): telegram chat username + chat_id (str): telegram chat id + + """ username = StringField(max_length=50) chat_id = StringField(required=True, max_length=50, unique=True) @@ -48,9 +63,23 @@ def __str__(self): f"{self.chat_id}".strip() def notify(self, update_message): + """Notify observer of update message. + + Calls: + >>> self._send_update_message(update_message) + + Args: + update_message (UpdateMessage): update message to be notified + + """ self._send_update_message(update_message) def _send_update_message(self, update_message): + """Send update message to telegram chat and creates it's respective ObserverMessage + + Args: + update_message (UpdateMessage): update message to be sent + """ telegram_message = BotTelegramCore.send_message( f'{update_message}', chat_id=self.chat_id) ObserverMessage( @@ -61,19 +90,46 @@ def _send_update_message(self, update_message): @classmethod def get_official_observer(cls): + """get official observer from official chat_id + + Returns: + Observer: official observer + """ return cls.objects.get(chat_id=BotTelegramCore.instance().chat_id) class UserObserver(Observer): + """MongoDB Document for user's observer + + Attributes: + username (str): telegram chat username + chat_id (str): telegram chat id + messages (list of ObserverMessage): list of ObserverMessage's + """ messages = ListField( ReferenceField(ObserverMessage, reverse_delete_rule=NULLIFY) ) def notify(self, update_message): + """Notify observer of update message. + + Calls: + >>> self._remove_last_message_from_subject(update_message.subject) + >>> self._send_update_message(update_message) + + Args: + update_message (UpdateMessage): update message to be notified + + """ self._remove_last_message_from_subject(update_message.subject) self._send_update_message(update_message) def _send_update_message(self, update_message): + """Forward official channel update message to telegram chat and creates it's respective ObserverMessage + + Args: + update_message (UpdateMessage): update message to be forwarded + """ official_observer = Observer.get_official_observer() last_official_message = ObserverMessage\ .objects(subject=update_message.subject, @@ -93,6 +149,11 @@ def _send_update_message(self, update_message): self.save() def _remove_last_message_from_subject(self, subject): + """Delete previous forwarded official channel update message from subject on telegram chat and removes it's respective ObserverMessage + + Args: + subject (Subject): subject to be filter messages + """ self.reload() try: observer_messages = filter( @@ -113,5 +174,3 @@ def _remove_last_message_from_subject(self, subject): pass except BadRequest as e: logger.warning(f'BadRequest {e}') - except Exception as e: - logger.error(e) diff --git a/db/subject.py b/db/subject.py index 67f6714..e7eb029 100644 --- a/db/subject.py +++ b/db/subject.py @@ -18,6 +18,15 @@ class Subject(Document): + """MongoDB Document for a split ticket VSP + + Attributes: + emoji (str): A string emoji + name (str): name of split ticket VSP + uri (str): websocket URI + observers (list of UserObserver): observers watching this subject + """ + emoji = StringField(required=True, max_length=2) name = StringField(required=True, max_length=55, unique=True) uri = StringField(required=True, max_length=120, unique=True) @@ -31,23 +40,47 @@ def __str__(self): @property def header(self): + """str headear for subject + + Returns: + str: emoji + name + """ return f"{self.emoji} {self.name}" def subscribe(self, observer): + """Subscribe a Observer to this subject + + Args: + observer (Observer): observer to subscribe + Raises: + ObserverAlreadyRegisteredError: if observer is already subscribed to subject + """ if observer in self.observers: raise ObserverAlreadyRegisteredError(f"Observer {observer} " - f"is already registered!") + f"is already subscribed!") self.observers.append(observer) self.save() def unsubscribe(self, observer): + """Unsubscribe a Observer to this subject + + Args: + observer (Observer): observer to unsubscribe + Raises: + ObserverNotRegisteredError: if observer is not subscribed + """ if observer not in self.observers: raise ObserverNotRegisteredError(f"Observer {observer} " - f"is not registered!") + f"is not subscribed!") self.observers.remove(observer) self.save() def notify(self, update_message): + """Notify official Observer and UserObserver's subscribed of some UpdateMessage + + Args: + update_message (UpdateMessage): update message to be notified + """ official_observer = Observer.get_official_observer() logger.info(f'Notifying official observer {official_observer} ' f'for {self}') diff --git a/db/update_message.py b/db/update_message.py index 8a6b0a7..69e465a 100644 --- a/db/update_message.py +++ b/db/update_message.py @@ -10,6 +10,11 @@ class Amount(EmbeddedDocument): + """MongoDB EmbeddedDocument for some amount value in ATOM + + Attributes: + _value (int): atom value + """ ATOM_DECIMALS = 100000000 _value = IntField(required=True) @@ -19,6 +24,17 @@ def __str__(self): @property def value(self): + """Value get property method + + Returns: + float: the value of amount in DCR + + Args: + value: desired value + + Raises: + TypeError: if value is not int + """ return self._value/self.ATOM_DECIMALS @value.setter @@ -29,6 +45,12 @@ def value(self, value: int): class Session(EmbeddedDocument): + """MongoDB EmbeddedDocument for a session data + + Attributes: + hash (str): session id + amounts (list of Amount): list of Amount's in session + """ hash = StringField(required=True) amounts = EmbeddedDocumentListField(Amount, required=True) @@ -44,6 +66,17 @@ def __str__(self): @classmethod def from_data(cls, data): + """Create a session from a data + + Examples: + >>> session = Session.from_data({'name': 'some_hash', 'amounts': [1000000000, 200000000]}) + + Args: + data: data to create a Session and it's respective Amount's + + Returns: + Session: Session created + """ instance = cls(data.get('name')) for amount in data.get('amounts'): instance.amounts.append(Amount(amount)) @@ -51,6 +84,13 @@ def from_data(cls, data): class UpdateMessage(Document): + """MongoDB Document for a update message + + Attributes: + subject (Subject): subject of this update message + sessions (list of Session): list of sessions + datetime: now() datetime + """ subject = ReferenceField(Subject, required=True) sessions = EmbeddedDocumentListField(Session, required=True) datetime = DateTimeField(default=pendulum.now, required=True) @@ -64,6 +104,19 @@ def __str__(self): @classmethod def from_data(cls, subject, msg): + """Create a update message from a data + + Examples: + >>> subject = Subject() + >>> update_message = UpdateMessage.from_data(subject, [{'name': 'some_hash', 'amounts': [1000000000, 200000000]}]) + + Args: + msg: msg received from websocket to create a UpdateMessage and it's respective Session's + subject Subject: Subject for UpdateMessage + + Returns: + UpdateMessage: UpdateMessage created + """ json_data = loads(msg) instance = cls(subject=subject) for data in json_data: diff --git a/requirements-dev.txt b/requirements-dev.txt index 6ca0269..cc21733 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -4,4 +4,6 @@ flake8==3.7.8 mongomock==3.18.0 pytest==5.2.2 pytest-cov==2.8.1 -codacy-coverage==1.3.11 \ No newline at end of file +codacy-coverage==1.3.11 +sphinx==2.2.2 +sphinx-rtd-theme==0.4.3 \ No newline at end of file From 22aad85d0771eacadbfccdb7e63dacb1f9466057 Mon Sep 17 00:00:00 2001 From: rodrigondec Date: Wed, 11 Dec 2019 21:39:21 -0300 Subject: [PATCH 2/4] docs created --- docs/.nojekyll | 0 docs/Makefile | 20 +++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++ docs/source/conf.py | 59 +++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 20 +++++++++++++++ 5 files changed, 134 insertions(+) create mode 100644 docs/.nojekyll create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..cbad490 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,59 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + + +# -- Project information ----------------------------------------------------- + +project = 'JackBot' +copyright = '2019, Rodrigo Castro & Fernando Guisso' +author = 'Rodrigo Castro & Fernando Guisso' + +# The full version, including alpha/beta/rc tags +release = '0.2.3' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon' +] + +autodoc_mock_imports = ["mongoengine", "connect"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..8f9d303 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. JackBot documentation master file, created by + sphinx-quickstart on Wed Dec 11 20:40:04 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to JackBot's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` From 2e76a30fa508c3ae5a37840a6933e4dd06ba9b7f Mon Sep 17 00:00:00 2001 From: rodrigondec Date: Wed, 11 Dec 2019 21:43:45 -0300 Subject: [PATCH 3/4] modules created --- docs/source/index.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8f9d303..dd25e91 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,10 @@ Welcome to JackBot's documentation! :maxdepth: 2 :caption: Contents: + bot + db + sws + Indices and tables From 8f465973c29fc06a2a0a178fec7f0c597c5a916a Mon Sep 17 00:00:00 2001 From: rodrigondec Date: Wed, 11 Dec 2019 21:44:05 -0300 Subject: [PATCH 4/4] autodoc files created --- docs/source/bot.commands.rst | 38 ++++++++++++++++++++ docs/source/bot.rst | 53 ++++++++++++++++++++++++++++ docs/source/db.rst | 46 ++++++++++++++++++++++++ docs/source/init_subjects_script.rst | 7 ++++ docs/source/modules.rst | 11 ++++++ docs/source/sws.rst | 30 ++++++++++++++++ docs/source/tests.db.rst | 46 ++++++++++++++++++++++++ docs/source/tests.rst | 30 ++++++++++++++++ docs/source/tests.sws.rst | 22 ++++++++++++ 9 files changed, 283 insertions(+) create mode 100644 docs/source/bot.commands.rst create mode 100644 docs/source/bot.rst create mode 100644 docs/source/db.rst create mode 100644 docs/source/init_subjects_script.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/sws.rst create mode 100644 docs/source/tests.db.rst create mode 100644 docs/source/tests.rst create mode 100644 docs/source/tests.sws.rst diff --git a/docs/source/bot.commands.rst b/docs/source/bot.commands.rst new file mode 100644 index 0000000..0731681 --- /dev/null +++ b/docs/source/bot.commands.rst @@ -0,0 +1,38 @@ +bot.commands package +==================== + +Submodules +---------- + +bot.commands.base module +------------------------ + +.. automodule:: bot.commands.base + :members: + :undoc-members: + :show-inheritance: + +bot.commands.callback module +---------------------------- + +.. automodule:: bot.commands.callback + :members: + :undoc-members: + :show-inheritance: + +bot.commands.subscription module +-------------------------------- + +.. automodule:: bot.commands.subscription + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: bot.commands + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/bot.rst b/docs/source/bot.rst new file mode 100644 index 0000000..bbc0dcc --- /dev/null +++ b/docs/source/bot.rst @@ -0,0 +1,53 @@ +bot package +=========== + +Subpackages +----------- + +.. toctree:: + + bot.commands + +Submodules +---------- + +bot.core module +--------------- + +.. automodule:: bot.core + :members: + :undoc-members: + :show-inheritance: + +bot.jack module +--------------- + +.. automodule:: bot.jack + :members: + :undoc-members: + :show-inheritance: + +bot.messages module +------------------- + +.. automodule:: bot.messages + :members: + :undoc-members: + :show-inheritance: + +bot.utils module +---------------- + +.. automodule:: bot.utils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: bot + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/db.rst b/docs/source/db.rst new file mode 100644 index 0000000..ffdeccf --- /dev/null +++ b/docs/source/db.rst @@ -0,0 +1,46 @@ +db package +========== + +Submodules +---------- + +db.exceptions module +-------------------- + +.. automodule:: db.exceptions + :members: + :undoc-members: + :show-inheritance: + +db.observer module +------------------ + +.. automodule:: db.observer + :members: + :undoc-members: + :show-inheritance: + +db.subject module +----------------- + +.. automodule:: db.subject + :members: + :undoc-members: + :show-inheritance: + +db.update\_message module +------------------------- + +.. automodule:: db.update_message + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: db + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/init_subjects_script.rst b/docs/source/init_subjects_script.rst new file mode 100644 index 0000000..0b47e66 --- /dev/null +++ b/docs/source/init_subjects_script.rst @@ -0,0 +1,7 @@ +init\_subjects\_script module +============================= + +.. automodule:: init_subjects_script + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..f389de9 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,11 @@ +JackBot +======= + +.. toctree:: + :maxdepth: 4 + + bot + db + init_subjects_script + sws + tests diff --git a/docs/source/sws.rst b/docs/source/sws.rst new file mode 100644 index 0000000..73cd9fc --- /dev/null +++ b/docs/source/sws.rst @@ -0,0 +1,30 @@ +sws package +=========== + +Submodules +---------- + +sws.client module +----------------- + +.. automodule:: sws.client + :members: + :undoc-members: + :show-inheritance: + +sws.exceptions module +--------------------- + +.. automodule:: sws.exceptions + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: sws + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/tests.db.rst b/docs/source/tests.db.rst new file mode 100644 index 0000000..d6315c3 --- /dev/null +++ b/docs/source/tests.db.rst @@ -0,0 +1,46 @@ +tests.db package +================ + +Submodules +---------- + +tests.db.test\_amount module +---------------------------- + +.. automodule:: tests.db.test_amount + :members: + :undoc-members: + :show-inheritance: + +tests.db.test\_session module +----------------------------- + +.. automodule:: tests.db.test_session + :members: + :undoc-members: + :show-inheritance: + +tests.db.test\_subject module +----------------------------- + +.. automodule:: tests.db.test_subject + :members: + :undoc-members: + :show-inheritance: + +tests.db.test\_update\_message module +------------------------------------- + +.. automodule:: tests.db.test_update_message + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: tests.db + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/tests.rst b/docs/source/tests.rst new file mode 100644 index 0000000..85a5682 --- /dev/null +++ b/docs/source/tests.rst @@ -0,0 +1,30 @@ +tests package +============= + +Subpackages +----------- + +.. toctree:: + + tests.db + tests.sws + +Submodules +---------- + +tests.fixtures module +--------------------- + +.. automodule:: tests.fixtures + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: tests + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/tests.sws.rst b/docs/source/tests.sws.rst new file mode 100644 index 0000000..2f556e6 --- /dev/null +++ b/docs/source/tests.sws.rst @@ -0,0 +1,22 @@ +tests.sws package +================= + +Submodules +---------- + +tests.sws.test\_client module +----------------------------- + +.. automodule:: tests.sws.test_client + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: tests.sws + :members: + :undoc-members: + :show-inheritance: