move gallery to source code and update distribution manifest

MANIFEST.in

@@ -8,3 +8,6 @@ include *.txt
 include *.rst
 exclude *.pyc
 exclude *.pyo
+exclude zelfred/docs/**.*
+exclude zelfred/tests/**.*
+exclude zelfred/gallery/**.*

docs/source/02-App-Gallery/helper.py

@@ -9,8 +9,12 @@
 dir_project_root = Path(__file__).absolute().parent.parent.parent.parent
 
 
-def print_commands(path_py: Path):
-    filename = path_py.stem.split("_", 1)[1]
+def print_commands(filename: str):
+    if not filename.endswith(".py"):
+        filename = filename + ".py"
+    path_py = dir_project_root.joinpath("zelfred", "gallery", filename)
+    if not path_py.exists():
+        raise FileNotFoundError
 
     print("--- first cd to this dir ---")
     print(f"cd {dir_project_root}")
@@ -24,13 +28,9 @@ def print_commands(path_py: Path):
     print("\n--- asciinema record command ---")
     print(" ".join(args))
 
-    print("\n--- enter virtualenv ---")
-    print("source .venv/bin/activate")
-
-    print("\n--- enter virtualenv ---")
+    print("\n--- enter virtualenv and run app ---")
     relpath = path_py.relative_to(dir_project_root)
-    args = ["python", f"{relpath}"]
-    print(" ".join(args))
+    print(f"source .venv/bin/activate && python {relpath}")
 
     print("\n--- asciinema upload ---")
     args = [
@@ -42,13 +42,11 @@ def print_commands(path_py: Path):
 
     print("then you can make it public and update the name")
     print("\n--- asciinema recording name ---")
-    print(f"zelfred app gallery - {filename}")
+    asciinema_name = filename.split("_", 1)[1].split(".", 1)[0]
+    print(f"zelfred app gallery - {asciinema_name}")
     print("\n--- asciinema recording description ---")
     print("https://github.com/MacHu-GWU/zelfred-project")
 
 
 if __name__ == "__main__":
-    p = Path(
-        "/Users/my-username/Documents/GitHub/zelfred-project/docs/source/02-App-Gallery/e01_random_password_generator.py"
-    )
-    print_commands(p)
+    print_commands("e10_refresh_cache_v3.py")

docs/source/02-App-Gallery/index.rst

@@ -17,7 +17,7 @@ The user enters the length of the password, and the UI generates a few random pa
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e01_random_password_generator.py
+    .. literalinclude:: ../../../zelfred/gallery/./e01_random_password_generator.py
        :language: python
        :linenos:
 
@@ -35,7 +35,7 @@ The user enters (or paste) the absolute path of the file, and the UI generates a
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e02_calculate_file_checksum.py
+    .. literalinclude:: ../../../zelfred/gallery/./e02_calculate_file_checksum.py
        :language: python
        :linenos:
 
@@ -53,7 +53,7 @@ Use the user input to sort a list of items by fuzzy match similarity. Allow user
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e03_select_item_using_fuzzy_match.py
+    .. literalinclude:: ../../../zelfred/gallery/./e03_select_item_using_fuzzy_match.py
        :language: python
        :linenos:
 
@@ -71,7 +71,7 @@ The user types a query and receives a dropdown list of Google search suggestions
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e04_google_search_with_suggestion.py
+    .. literalinclude:: ../../../zelfred/gallery/./e04_google_search_with_suggestion.py
        :language: python
        :linenos:
 
@@ -89,7 +89,7 @@ User type query and return a dropdown list of matched Google Chrome bookmarks. U
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e05_search_google_chrome_bookmark.py
+    .. literalinclude:: ../../../zelfred/gallery/./e05_search_google_chrome_bookmark.py
        :language: python
        :linenos:
 
@@ -109,7 +109,7 @@ User can search folder in a root directory, and then tap "Enter" to enter a sub
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e06_folder_and_file_search.py
+    .. literalinclude:: ../../../zelfred/gallery/./e06_folder_and_file_search.py
        :language: python
        :linenos:
 
@@ -127,12 +127,12 @@ User the user input to search the username, allow user to tap "Ctrl A" to copy t
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e05_password_book.py
+    .. literalinclude:: ../../../zelfred/gallery/./e05_password_book.py
        :language: python
        :linenos:
 
 
-Refresh Cache
+Refresh Cache V1
 ------------------------------------------------------------------------------
 :bdg-warning:`Difficulty: Medium`
 
@@ -145,7 +145,43 @@ No matter what user entered, always return a random value between 1 and 100. And
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e08_refresh_cache.py
+    .. literalinclude:: ../../../zelfred/gallery/./e08_refresh_cache_v1.py
+       :language: python
+       :linenos:
+
+
+Refresh Cache V2
+------------------------------------------------------------------------------
+:bdg-warning:`Difficulty: Medium`
+
+No matter what user entered, always return a random value between 1 and 100. And this value is based on cache that won't change while user is typing. However, we want to provide a way to refresh the value. User can type "!~", then the value will be immediately refreshed, and the "!~" will be removed automatically.
+
+**Demo**
+
+.. image:: https://asciinema.org/a/631325.svg
+    :target: https://asciinema.org/a/631325
+
+.. dropdown:: **Source Code**
+
+    .. literalinclude:: ../../../zelfred/gallery/./e09_refresh_cache_v2.py
+       :language: python
+       :linenos:
+
+
+Refresh Cache V3
+------------------------------------------------------------------------------
+:bdg-warning:`Difficulty: Medium`
+
+No matter what user entered, always return a random value between 1 and 100. And this value is based on cache that won't change while user is typing. However, we want to provide a way to refresh the value. User can type "!~", then the value will be refreshed after 1 seconds, and the "!~" will be removed automatically. During the waiting, it will show a helper text to tell user to wait.
+
+**Demo**
+
+.. image:: https://asciinema.org/a/631335.svg
+    :target: https://asciinema.org/a/631335
+
+.. dropdown:: **Source Code**
+
+    .. literalinclude:: ../../../zelfred/gallery/./e10_refresh_cache_v3.py
        :language: python
        :linenos:
 
@@ -161,6 +197,6 @@ Copy JSON text to clipboard, then hit 'Enter' to dump the formatted JSON to
 
 .. dropdown:: **Source Code**
 
-    .. literalinclude:: ./e09_json_formatter.py
+    .. literalinclude:: ../../../zelfred/gallery/./e11_json_formatter.py
        :language: python
        :linenos:

docs/source/zelfred/__init__.rst

@@ -10,6 +10,7 @@ sub packages and modules
 .. toctree::
     :maxdepth: 1
 
+    gallery <gallery/__init__>
     action <action>
     api <api>
     constants <constants>

docs/source/zelfred/gallery/__init__.rst

@@ -0,0 +1,24 @@
+gallery
+=======
+
+.. automodule:: zelfred.gallery
+    :members:
+
+sub packages and modules
+------------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    e01_random_password_generator <e01_random_password_generator>
+    e02_calculate_file_checksum <e02_calculate_file_checksum>
+    e03_select_item_using_fuzzy_match <e03_select_item_using_fuzzy_match>
+    e04_google_search_with_suggestion <e04_google_search_with_suggestion>
+    e05_search_google_chrome_bookmark <e05_search_google_chrome_bookmark>
+    e06_folder_and_file_search <e06_folder_and_file_search>
+    e07_password_book <e07_password_book>
+    e08_refresh_cache_v1 <e08_refresh_cache_v1>
+    e09_refresh_cache_v2 <e09_refresh_cache_v2>
+    e09_refresh_cache_v3 <e09_refresh_cache_v3>
+    e10_json_formatter <e10_json_formatter>
+

docs/source/zelfred/gallery/e01_random_password_generator.rst

@@ -0,0 +1,5 @@
+e01_random_password_generator
+=============================
+
+.. automodule:: zelfred.gallery.e01_random_password_generator
+    :members:

docs/source/zelfred/gallery/e02_calculate_file_checksum.rst

@@ -0,0 +1,5 @@
+e02_calculate_file_checksum
+===========================
+
+.. automodule:: zelfred.gallery.e02_calculate_file_checksum
+    :members:

docs/source/zelfred/gallery/e03_select_item_using_fuzzy_match.rst

@@ -0,0 +1,5 @@
+e03_select_item_using_fuzzy_match
+=================================
+
+.. automodule:: zelfred.gallery.e03_select_item_using_fuzzy_match
+    :members:

docs/source/zelfred/gallery/e04_google_search_with_suggestion.rst

@@ -0,0 +1,5 @@
+e04_google_search_with_suggestion
+=================================
+
+.. automodule:: zelfred.gallery.e04_google_search_with_suggestion
+    :members:

docs/source/zelfred/gallery/e05_search_google_chrome_bookmark.rst

@@ -0,0 +1,5 @@
+e05_search_google_chrome_bookmark
+=================================
+
+.. automodule:: zelfred.gallery.e05_search_google_chrome_bookmark
+    :members:

docs/source/zelfred/gallery/e06_folder_and_file_search.rst

@@ -0,0 +1,5 @@
+e06_folder_and_file_search
+==========================
+
+.. automodule:: zelfred.gallery.e06_folder_and_file_search
+    :members:

docs/source/zelfred/gallery/e07_password_book.rst

@@ -0,0 +1,5 @@
+e07_password_book
+=================
+
+.. automodule:: zelfred.gallery.e07_password_book
+    :members:

docs/source/zelfred/gallery/e08_refresh_cache_v1.rst

@@ -0,0 +1,5 @@
+e08_refresh_cache_v1
+====================
+
+.. automodule:: zelfred.gallery.e08_refresh_cache_v1
+    :members:

docs/source/zelfred/gallery/e09_refresh_cache_v2.rst

@@ -0,0 +1,5 @@
+e09_refresh_cache_v2
+====================
+
+.. automodule:: zelfred.gallery.e09_refresh_cache_v2
+    :members:

docs/source/zelfred/gallery/e09_refresh_cache_v3.rst

@@ -0,0 +1,5 @@
+e09_refresh_cache_v3
+====================
+
+.. automodule:: zelfred.gallery.e09_refresh_cache_v3
+    :members:

docs/source/zelfred/gallery/e10_json_formatter.rst

@@ -0,0 +1,5 @@
+e10_json_formatter
+==================
+
+.. automodule:: zelfred.gallery.e10_json_formatter
+    :members:

zelfred/gallery/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

docs/source/02-App-Gallery/e08_refresh_cache.py → zelfred/gallery/e08_refresh_cache_v1.py

@@ -65,7 +65,7 @@ def handler(query: str, ui: zf.UI):
                 title="Refresh value",
                 subtitle=f"Hit {ui.render.ENTER} to refresh the value",
                 variables={"n_backspace": len(after_query) + 2},
-            )
+            ),
         ]
     # otherwise, always return a random value, and cache it
     else:
@@ -74,6 +74,7 @@ def handler(query: str, ui: zf.UI):
         return [
             zf.Item(
                 title=f"Value {cache.value}",
+                subtitle=f"Type !~ to refresh the value",
             )
         ]
 

zelfred/gallery/e09_refresh_cache_v2.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+
+"""
+Feature:
+
+No matter what user entered, always return a random value between 1 and 100.
+And this value is based on cache that won't change while user is typing.
+However, we want to provide a way to refresh the value. User can type "!~",
+then the value will be immediately refreshed, and the "!~" will be removed
+automatically.
+
+Difficulty: Medium
+
+Dependencies: NA
+
+Demo: https://asciinema.org/a/631325
+"""
+
+import random
+
+import zelfred.api as zf
+
+
+class Cache:
+    def __init__(self):
+        self.value = None
+
+
+cache = Cache()
+
+
+def handler(query: str, ui: zf.UI):
+    """
+    The handler is the core of a Zelfred App. It's a user-defined function
+    that takes the entered query and the UI object as inputs and returns
+    a list of items to render.
+    """
+    # if query is for refresh value
+    if "!~" in query:
+        # refresh the value
+        cache.value = random.randint(1, 100)
+        # remove the "!~" from the query in the UI
+        ui.line_editor.press_backspace(2)
+        return [
+            zf.Item(
+                title=f"Value {cache.value}",
+                subtitle=f"Type !~ to refresh the value",
+            )
+        ]
+    # otherwise, always return a random value, and cache it
+    else:
+        if cache.value is None:
+            cache.value = random.randint(1, 100)
+        return [
+            zf.Item(
+                title=f"Value {cache.value}",
+                subtitle=f"Type !~ to refresh the value",
+            )
+        ]
+
+
+if __name__ == "__main__":
+    # reset the debugger and enable it
+    zf.debugger.reset()
+    zf.debugger.enable()
+
+    # create the UI and run it
+    ui = zf.UI(handler=handler, capture_error=True)
+    ui.run()