Add more detailed design for plugin architecture

There is now an initial implementation that defines the
plugin as iterator. The idea is that this would be better
approach for large amounts of data than simple list.

WIP

Signed-off-by: Heikki Laaksonen <laaksonen.heikki.j@gmail.com>

setup.py

@@ -1,8 +1,6 @@
-#!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#  SPDX-License-Identifier: Apache-2.0
-#
+#  Snippy-tldr - A plugin to import tldr man pages for Snippy.
 #  Copyright 2019 Heikki J. Laaksonen  <laaksonen.heikki.j@gmail.com>
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,6 +14,8 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
 
 """setup: Install Snippy tool."""
 
@@ -56,7 +56,7 @@
     description='Snippy plugin to import tldr man pages.',
     long_description=README,
     long_description_content_type='text/x-rst',
-    py_modules=['snippy_tldr'],
+    packages=['snippy_tldr'],
     python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*',
     install_requires=REQUIRES,
     zip_safe=False,
@@ -89,7 +89,7 @@
     test_suite='tests',
     entry_points={
         'snippyplugin': [
-            'tldr = snippy_tldr'
+            'snippy = snippy_tldr.plugin'
         ]
     }
 )

snippy_tldr/plugin.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#  SPDX-License-Identifier: Apache-2.0
-#
+#  Snippy-tldr - A plugin to import tldr man pages for Snippy.
 #  Copyright 2019 Heikki J. Laaksonen  <laaksonen.heikki.j@gmail.com>
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,17 +15,112 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
 
 """Snippy-tldr is a plugin to import tldr man pages for snippy."""
 
+
+def snippy_import_hook(validator, parser, uri):
+    """Import notes for Snippy.
+
+    This is an import hook that returns an iterator object. The iterator must
+    be an iterable class that implements next() and len() methods. The iterator
+    must return JSON structures that pass the ``validate.note()``.
+
+    If suitable, the ``parse`` object may be used to parse the source data to
+    JSON note for Snippy.
+
+    Args
+        validate (obj): A ``SnippyNotesValidator`` object to validate JSON notes.
+        parse (obj): A ``SnippyNotesParser`` to parse notes attributes.
+        uri (str): The value of ``-f|--file`` command line option from Snippy tool.
+
+    Returns:
+        obj: Iterator object to store JSON notes.
+
+    Examples
+    --------
+    >>> def __init__(self, validator, parser, uri):
+    >>>     self.validate = Validator
+    >>>     self.parse = parser
+    >>>     self.uri = uri
+    >>>     self._parse_notes()
+    >>>
+    >>> def _parse_notes(self):
+    >>>     filename = 'notes-list.md'
+    >>>     with open(filename, 'w') as infile:
+    >>>         note = self._parse_note(infile)
+    >>>         if validate.note(note):
+    >>>             self.notes.append(note)
+    >>>
+    >>> def _parse_note(self, infile)
+    >>>     note = {}
+    >>>     note['category'] = self.parse
+    """
+
+    tldr = SnippyTldr(validator, parser, uri)
+
+    return tldr
+
+
 class SnippyTldr(object):  # pylint: disable=too-few-public-methods
     """Plugin to import tldr man pages for snippy."""
 
-    def __init__(self):
-        print("hello from snippy-tldr")
+    def __init__(self, validator, parser, uri):
+        self._validate = validator
+        self._parse = parser
+        self._uri = uri
+        self._notes = []
+        self._i = 0
+
+        self._parse_notes()
+
+    def __len__(self):
+        """Return count of the notes.
+
+        Returns:
+            int: The len of the iterator object.
+        """
+
+        return len(self._notes)
+
+    def __iter__(self):
+        return self
+
+    def next(self):
+        """Return the next note.
+
+        Returns:
+            dict: The next note in interator.
+        """
+
+        if self._i < len(self):
+            note = self._notes[self._i]
+            self._i += 1
+        else:
+            raise StopIteration
+
+        return note
+
+    def _parse_notes(self):
+        """Parse notes."""
 
-    @staticmethod
-    def run():
-        """Dummy run."""
+        self._notes.append({
+            'category': 'snippet',
+            'data': 'docker ps',
+            'brief': 'print containers',
+            'description': 'long description',
+            'name': 'note name',
+            'groups': ('docker',),
+            'tags': ('tags', 'tag2'),
+            'links': ('http://link.html',),
+            'source': 'note source',
+            'versions': ('tldr>=0.10.0',),
+            'languages': ('python>=0.10.0',),
+            'filename': 'filename.txt'})
 
-        print("hello from run")
+    # Python 3 compatible iterator [1].
+    #
+    # [1] https://stackoverflow.com/a/28353158
+    __next__ = next

tests/conftest.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-#  SPDX-License-Identifier: Apache-2.0
-#
+#  Snippy-tldr - A plugin to import tldr man pages for Snippy.
 #  Copyright 2019 Heikki J. Laaksonen  <laaksonen.heikki.j@gmail.com>
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,5 +14,7 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
 
 """conftest: Fixtures for pytest."""

tests/test_snippy_tldr.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-#  SPDX-License-Identifier: Apache-2.0
-#
+#  Snippy-tldr - A plugin to import tldr man pages for Snippy.
 #  Copyright 2019 Heikki J. Laaksonen  <laaksonen.heikki.j@gmail.com>
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,10 +14,12 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
 
 """test-snippy-tldr: Test snippy plugin to import tldr man pages."""
 
-from snippy_tldr import SnippyTldr
+from snippy_tldr.plugin import SnippyTldr
 
 
 class TestSnippyTldr(object):  # pylint: disable=too-few-public-methods
@@ -28,7 +29,6 @@ class TestSnippyTldr(object):  # pylint: disable=too-few-public-methods
     def test_001():
         """First test."""
 
-        tldr = SnippyTldr()
-        tldr.run()
+        _ = SnippyTldr("test", "test", "test")
 
         assert 1