make user history installable

README.md

@@ -12,7 +12,7 @@ hf_oauth: true
 
 # Bring User History to your Spaces 🚀
 
-***User History*** is a plugin that you can add to your Spaces to cache generated images for your users.
+**Gradio User History** is a plugin (and package) that caches generated images for your Space users.
 
 ## Key features:
 
@@ -27,59 +27,61 @@ Want more? Please open an issue in the [Community Tab](https://huggingface.co/sp
 
 ## Integration
 
-To integrate ***User History***, only a few steps are required:
-1. Enable OAuth in your Space by adding `oauth: true` to your README (see [here](https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/README.md?code=true#L10))
-2. Add a Persistent Storage in your Space settings. Without it, the history will not be saved permanently. Every restart of your Space will erase all the data. If you start with a small tier, it's always possible to increase the disk space later without loosing the data.
-3. Copy [`user_history.py`](https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/user_history.py) at the root of your project.
-4. Import in your main file with `import user_history` (see [here](https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/app.py#L10))
-5. Integrate to your `generate`-like methods. Any function called by Gradio and that generates one or multiple images is a good candidate.
-   1. Add `profile: gr.OAuthProfile | None` as argument to the function (see [here](https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/app.py#L16)). This will tell Gradio that it needs to inject the user profile for you.
-   2. Use `user_history.save_image(label=..., image=..., profile=profile, metadata=...)` (as done [here](https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/app.py#L32))
-      1. `label` is the label of the image. Usually the prompt used to generate it.
-      2. `image` is the generated image. It can be a path to a stored image, a `PIL.Image` object or a numpy array.
-      3. `profile` is the user profile injected by Gradio
-      4. `metadata` (optional) is any additional information you want to add. It has to be a json-able dictionary.
-   3. Finally use `user_history.render()` to render the "Past generations" section (see [here](https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/app.py#L53)). A good practice is to set it in a different tab to avoid overloading your first page. You don't have to modify anything of your existing `gr.Blocks` section: just render it inside a Tab.
+Integrate *Gradio User History* in just a few steps:
 
-## Example
+1. Enable OAuth
 
-Here is a minimal example illustrating what we saw above.
+```yaml
+# README.md
+---
+hf_oauth: true
+---
+```
+
+2. Add dependency in `requirements.txt`
+
+```bash
+# requirements.txt
+git+https://huggingface.co/spaces/Wauplin/gradio-user-history
+```
+
+3. Integrate into your Gradio app
 
 ```py
+# app.py
 import gradio as gr
-import user_history  # 0. Import user_history
+import gradio_user_history as gr_user_history
+(...)
 
-# 1. Inject user profile
+# => Inject gr.OAuthProfile
 def generate(prompt: str, profile: gr.OAuthProfile | None):
     image = ...
 
-    # 2. Save image
-    user_history.save_image(label=prompt, image=image, profile=profile)
+    # => Save generated image(s)
+    gr_user_history.save_image(label=prompt, image=image, profile=profile)
     return image
 
 
-with gr.Blocks(css="style.css") as demo:
-    with gr.Group():
-        prompt = gr.Text(show_label=False, placeholder="Prompt")
-        gallery = gr.Image()
-    prompt.submit(fn=generate, inputs=prompt, outputs=gallery)
-
-# 3. Render user history
-with gr.Blocks() as demo_with_history:
-    with gr.Tab("Demo"):
-        demo.render()
-    with gr.Tab("Past generations"):
-        user_history.render()
+# => Render user history
+with gr.Blocks() as demo:
+    (...)
 
-demo_with_history.queue().launch()
+    # or `with gr.Tab("Past generations"):`
+    with gr.Accordion("Past generations", open=False):
+        gr_user_history.render()
 ```
 
+4. (optional) Add Persistent Storage in your Space settings.
+   Persistent Storage is suggested but not mandatory. If not enabled, the history is lost each time the Space restarts.
+
+And you're done!
+
 ## Useful links
 
 - **Demo:** https://huggingface.co/spaces/Wauplin/gradio-user-history
 - **README:** https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/README.md
 - **Source file:** https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/user_history.py
-- **Discussions:** https://huggingface.co/spaces/Wauplin/gradio-user-history/discussions
+- **Questions and feedback:** https://huggingface.co/spaces/Wauplin/gradio-user-history/discussions
 
 ## Preview
 

app.py

@@ -1,15 +1,13 @@
 #!/usr/bin/env python
-
 import json
 import pathlib
 import tempfile
 from pathlib import Path
 
 import gradio as gr
+import gradio_user_history as gr_user_history
 from gradio_client import Client
 
-import user_history
-
 
 client = Client("runwayml/stable-diffusion-v1-5")
 
@@ -30,7 +28,7 @@ def generate(prompt: str, profile: gr.OAuthProfile | None) -> tuple[str, list[st
 
     # Saving user history
     for path in paths:
-        user_history.save_image(label=prompt, image=path, profile=profile, metadata=metadata)
+        gr_user_history.save_image(label=prompt, image=path, profile=profile, metadata=metadata)
 
     return paths  # type: ignore
 
@@ -53,7 +51,7 @@ with gr.Blocks() as demo_with_history:
     with gr.Tab("Demo"):
         demo.render()
     with gr.Tab("Past generations"):
-        user_history.render()
+        gr_user_history.render()
 
 if __name__ == "__main__":
     demo_with_history.queue().launch()

setup.py

@@ -0,0 +1,57 @@
+from setuptools import find_packages, setup
+
+
+def get_version() -> str:
+    rel_path = "src/gradio_user_history/__init__.py"
+    with open(rel_path, "r") as fp:
+        for line in fp.read().splitlines():
+            if line.startswith("__version__"):
+                delim = '"' if '"' in line else "'"
+                return line.split(delim)[1]
+    raise RuntimeError("Unable to find version string.")
+
+
+install_requires = [
+    "gradio[oauth]>=3.44",
+]
+
+extras = {}
+
+extras["dev"] = [
+    "ruff",
+    "black",
+    "mypy",
+]
+
+
+setup(
+    name="gradio_user_history",
+    version=get_version(),
+    author="Lucain Pouget",
+    author_email="[email protected]",
+    description="A package to store user history in a gradio app.",
+    long_description=open("README.md", "r", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    keywords="gradio oauth machine-learning",
+    license="Apache",
+    url="https://huggingface.co/spaces/Wauplin/gradio-user-history",
+    package_dir={"": "src"},
+    packages=find_packages("src"),
+    extras_require=extras,
+    python_requires=">=3.8.0",
+    install_requires=install_requires,
+    classifiers=[
+        "Intended Audience :: Developers",
+        "Intended Audience :: Education",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+)

src/gradio_user_history/__init__.py

@@ -0,0 +1,21 @@
+"""
+User History is a plugin that you can add to your Spaces to cache generated images for your users.
+
+Key features:
+- 🤗 Sign in with Hugging Face
+- Save generated images with their metadata: prompts, timestamp, hyper-parameters, etc.
+- Export your history as zip.
+- Delete your history to respect privacy.
+- Compatible with Persistent Storage for long-term storage.
+- Admin panel to check configuration and disk usage .
+
+Useful links:
+- Demo: https://huggingface.co/spaces/Wauplin/gradio-user-history
+- README: https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/README.md
+- Source file: https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/user_history.py
+- Discussions: https://huggingface.co/spaces/Wauplin/gradio-user-history/discussions
+"""
+from ._user_history import render, save_image, setup  # noqa: F401
+
+
+__version__ = "0.1.0"

user_history.py → src/gradio_user_history/_user_history.py

@@ -1,20 +1,3 @@
-"""
-User History is a plugin that you can add to your Spaces to cache generated images for your users.
-
-Key features:
-- 🤗 Sign in with Hugging Face
-- Save generated images with their metadata: prompts, timestamp, hyper-parameters, etc.
-- Export your history as zip.
-- Delete your history to respect privacy.
-- Compatible with Persistent Storage for long-term storage.
-- Admin panel to check configuration and disk usage .
-
-Useful links:
-- Demo: https://huggingface.co/spaces/Wauplin/gradio-user-history
-- README: https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/README.md
-- Source file: https://huggingface.co/spaces/Wauplin/gradio-user-history/blob/main/user_history.py
-- Discussions: https://huggingface.co/spaces/Wauplin/gradio-user-history/discussions
-"""
 import json
 import os
 import shutil
@@ -89,7 +72,7 @@ def render() -> None:
     gallery = gr.Gallery(
         label="Past images",
         show_label=True,
-        elem_id="gallery",
+        elem_id="gradio_user_history_gallery",
         object_fit="contain",
         columns=5,
         height=600,
@@ -295,7 +278,7 @@ def _resolve_folder_path(folder_path: str | Path | None) -> Path:
         return Path("/data") / "_user_history"
 
     # Not in a Space or Persistent storage not enabled => local folder
-    return Path(__file__).parent / "_user_history"
+    return Path("_user_history").resolve()
 
 
 def _archives_path() -> Path: