Merge pull request #631 from hx2A/downloadlibraries

hx2A · web-flow · commit bd2493b39d53 · 2025-04-17T23:31:07.000-04:00
Download libraries
diff --git a/generator/reference.py b/generator/reference.py
@@ -354,6 +354,30 @@
             "None",
         )
     ],
+    ("Py5Tools", "processing_library_storage_dir"): [
+        (
+            [],
+            "Path",
+        )
+    ],
+    ("Py5Tools", "processing_installed_libraries"): [
+        (
+            [],
+            "list[str]",
+        )
+    ],
+    ("Py5Tools", "processing_check_library"): [
+        (
+            ["library_name: str"],
+            "bool",
+        )
+    ],
+    ("Py5Tools", "processing_download_library"): [
+        (
+            ["library_name: str"],
+            "bool",
+        )
+    ],
 }
 
 OPTIONAL_METHOD_SIGNATURES = {
diff --git a/py5_docs/Reference/api_en/Py5Tools_processing_check_library.txt b/py5_docs/Reference/api_en/Py5Tools_processing_check_library.txt
@@ -0,0 +1,16 @@
+@@ meta
+name = processing.check_library()
+type = function
+category = processing
+subcategory = None
+
+@@ signatures
+processing_check_library(library_name: str) -> bool
+
+@@ variables
+library_name: str - name of Processing library
+
+@@ description
+Check if a Processing library has been downloaded and stored by py5. These are the same libraries available to you in the Library Manager when you use the Processing Development Environment (PDE). Downloaded libraries are available for you to import in Python after you import py5.
+
+Downloaded libraries will be saved in the Processing library storage directory. Use [](py5tools_processing_library_storage_dir) to get the specific location of the storage directory on your machine.
diff --git a/py5_docs/Reference/api_en/Py5Tools_processing_download_library.txt b/py5_docs/Reference/api_en/Py5Tools_processing_download_library.txt
@@ -0,0 +1,16 @@
+@@ meta
+name = processing.download_library()
+type = function
+category = processing
+subcategory = None
+
+@@ signatures
+processing_download_library(library_name: str) -> bool
+
+@@ variables
+library_name: str - name of Processing library
+
+@@ description
+Download and store a Processing library. These are the same libraries available to you in the Library Manager when you use the Processing Development Environment (PDE). After this function downloads a Processing library, it will be available for you to import in Python after you import py5.
+
+Downloaded libraries will be saved in the Processing library storage directory. Use [](py5tools_processing_library_storage_dir) to get the specific location of the storage directory on your machine.
diff --git a/py5_docs/Reference/api_en/Py5Tools_processing_installed_libraries.txt b/py5_docs/Reference/api_en/Py5Tools_processing_installed_libraries.txt
@@ -0,0 +1,13 @@
+@@ meta
+name = processing.installed_libraries()
+type = function
+category = processing
+subcategory = None
+
+@@ signatures
+processing_installed_libraries() -> list[str]
+
+@@ description
+List the Processing libraries stored in your computer's Processing library storage directory. These are all of the Processing libraries that have been installed using the [](py5tools_processing_download_library) function. To get the location of the library storage directory, use the [](py5tools_processing_library_storage_dir) function.
+
+Downloaded libraries will be saved in the Processing library storage directory. Use [](py5tools_processing_library_storage_dir) to get the specific location of the storage directory on your machine.
diff --git a/py5_docs/Reference/api_en/Py5Tools_processing_library_storage_dir.txt b/py5_docs/Reference/api_en/Py5Tools_processing_library_storage_dir.txt
@@ -0,0 +1,13 @@
+@@ meta
+name = processing.library_storage_dir()
+type = function
+category = processing
+subcategory = None
+
+@@ signatures
+processing_library_storage_dir() -> Path
+
+@@ description
+Return the location of the Processing library storage directory. You should never need to manually edit files in this directory, but if for some reason you do, you'll first need to find it. By default, this will be `~/.cache/py5` on Linux and MacOS machines and `~/AppData/Local/py5` on Windows machines. These locations are similar to where other Python libraries store their data files. If you wish, set the `PY5_HOME` environment variable to move the storage directory to a location of your choosing.
+
+If you wish to add Java Jar files to py5's classpath, don't use this directory. Instead, put jars in a `jars` subdirectory (relative to the current working directory of your Python code) or set the `PY5_JARS` environment variable to the path of the directory you wish to use.
diff --git a/py5_resources/data/py5tools.csv b/py5_resources/data/py5tools.csv
@@ -16,4 +16,8 @@ live_coding_screenshot,,,function,live_coding,,PYTHON,live_coding
 live_coding_copy_code,,,function,live_coding,,PYTHON,live_coding
 live_coding_snapshot,,,function,live_coding,,PYTHON,live_coding
 live_coding_count,,,function,live_coding,,PYTHON,live_coding
-live_coding_activate,,,function,live_coding,,PYTHON,live_coding
+live_coding_activate,,,function,live_coding,,PYTHON,live_coding
+processing_library_storage_dir,,,function,processing,,PYTHON,processing
+processing_installed_libraries,,,function,processing,,PYTHON,processing
+processing_check_library,,,function,processing,,PYTHON,processing
+processing_download_library,,,function,processing,,PYTHON,processing
diff --git a/py5_resources/py5_module/py5/__init__.py b/py5_resources/py5_module/py5/__init__.py
@@ -41,6 +41,7 @@
 from jpype import JClass  # noqa
 from jpype.types import JArray, JChar, JFloat, JInt, JString  # noqa
 from PIL import Image  # noqa
+from py5_tools.constants import VERSION as __version__
 
 _environ = py5_tools.environ.Environment()
 
@@ -97,6 +98,8 @@
 
     # add py5 jars to the classpath first
     py5_tools.add_jars(str(base_path / "jars"))
+    # add stored processing libraries
+    py5_tools.add_jars(py5_tools.processing.library_storage_dir())
     # if the cwd has a jars subdirectory, add that next
     py5_tools.add_jars(Path("jars"))
     # if the PY5_JARS environment variable exists, add those jars
@@ -163,9 +166,6 @@
     # IPython must not be installed
     pass
 
-
-__version__ = "0.10.5.dev0"
-
 _PY5_USE_IMPORTED_MODE = py5_tools.get_imported_mode()
 py5_tools._lock_imported_mode()
 
diff --git a/py5_resources/py5_module/py5_tools/__init__.py b/py5_resources/py5_module/py5_tools/__init__.py
@@ -18,18 +18,16 @@
 #
 # *****************************************************************************
 """
-Utilities and accessory tools for py5. 
+Utilities and accessory tools for py5.
 """
 from . import live_coding  # noqa
+from . import processing  # noqa
 from . import translators  # noqa
 from .config import *  # noqa
+from .constants import VERSION as __version__
 from .hooks import *  # noqa
 from .imported import _lock_imported_mode, get_imported_mode, set_imported_mode  # noqa
 from .jvm import *  # noqa
-from .libraries import *  # noqa
-
-__version__ = "0.10.5.dev0"
-
 
 __all__ = [
     "__version__",
@@ -43,6 +41,7 @@
     "is_jvm_running",
     "live_coding",
     "offline_frame_processing",
+    "processing",
     "register_processing_mode_key",
     "save_frames",
     "screenshot",
diff --git a/py5_resources/py5_module/py5_tools/constants.py b/py5_resources/py5_module/py5_tools/constants.py
@@ -0,0 +1,31 @@
+# *****************************************************************************
+#
+#   Part of the py5 library
+#   Copyright (C) 2020-2025 Jim Schmitz
+#
+#   This library is free software: you can redistribute it and/or modify it
+#   under the terms of the GNU Lesser General Public License as published by
+#   the Free Software Foundation, either version 2.1 of the License, or (at
+#   your option) any later version.
+#
+#   This library is distributed in the hope that it will be useful, but
+#   WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+#   General Public License for more details.
+#
+#   You should have received a copy of the GNU Lesser General Public License
+#   along with this library. If not, see <https://www.gnu.org/licenses/>.
+#
+# *****************************************************************************
+import os
+import platform
+from pathlib import Path
+
+VERSION = "0.10.5.dev0"
+PROCESSING_BUILD_NUMBER = 1292
+
+if not (PY5_HOME := os.environ.get("PY5_HOME")):
+    if platform.system() == "Windows":
+        PY5_HOME = Path.home() / "AppData" / "Local" / "py5"
+    else:
+        PY5_HOME = Path.home() / ".cache" / "py5"
diff --git a/py5_resources/py5_module/py5_tools/environ.py b/py5_resources/py5_module/py5_tools/environ.py
@@ -17,8 +17,6 @@
 #   along with this library. If not, see <https://www.gnu.org/licenses/>.
 #
 # *****************************************************************************
-
-
 class Environment:
     def __init__(self):
         try:
diff --git a/py5_resources/py5_module/py5_tools/libraries.py b/py5_resources/py5_module/py5_tools/libraries.py
@@ -24,7 +24,9 @@
 
 import requests
 
-PROCESSING_LIBRARY_URL = "http://download.processing.org/contribs"
+from .constants import PROCESSING_BUILD_NUMBER
+
+PROCESSING_LIBRARY_URL = "https://contributions.processing.org/contribs.txt"
 
 PARAGRAPH_REGEX = re.compile("^paragraph=(.*?)^[a-z]*?=", re.DOTALL | re.MULTILINE)
 
@@ -54,6 +56,12 @@ def _load_data(self):
             libinfo["id"] = int(libinfo["id"])
             libinfo["minRevision"] = int(libinfo["minRevision"])
             libinfo["maxRevision"] = int(libinfo["maxRevision"])
+            libinfo["compatible"] = (
+                libinfo["maxRevision"] == 0
+                or libinfo["minRevision"]
+                <= PROCESSING_BUILD_NUMBER
+                <= libinfo["maxRevision"]
+            )
             libinfo["categories"] = libinfo["categories"].split(",")
             paragraph = PARAGRAPH_REGEX.findall(blocks[i])
             libinfo["paragraph"] = paragraph[0] if paragraph else ""
@@ -66,7 +74,6 @@ def _load_data(self):
         self._data = data
 
     def get_library_info(self, category=None, library_name=None, library_id=None):
-        # TODO: also make sure minRevision < version < maxRevision, but how?
         info = self._data
         if category:
             info = filter(lambda x: category in x.get("categories", []), info)
@@ -88,17 +95,27 @@ def download_zip(self, dest, library_name=None, library_id=None):
         info = info[0]
         download_url = info["download"]
 
+        if not info["compatible"]:
+            raise RuntimeError(
+                f"Library {library_name} is not compatible with the version of Processing py5 is currently using."
+            )
+
         response = requests.get(download_url)
         if response.status_code != 200:
             raise RuntimeError(f"could not download library at {download_url}")
 
         with zipfile.ZipFile(io.BytesIO(response.content)) as zf:
             jars = []
+            parts0 = None
             for name in zf.namelist():
                 path = Path(name)
                 if len(path.parts) > 2 and path.parts[1] == "library":
                     jars.append(name)
+                    if parts0 is None:
+                        parts0 = path.parts[0]
             zf.extractall(dest, jars)
 
+            return parts0
+
 
 __all__ = ["ProcessingLibraryInfo"]
diff --git a/py5_resources/py5_module/py5_tools/processing.py b/py5_resources/py5_module/py5_tools/processing.py
diff --git a/py5_resources/py5_module/py5_tools/tools/py5cmd.py b/py5_resources/py5_module/py5_tools/tools/py5cmd.py
diff --git a/py5_resources/py5_module/py5_tools/utilities.py b/py5_resources/py5_module/py5_tools/utilities.py
diff --git a/py5_resources/py5_module/pyproject.toml b/py5_resources/py5_module/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -17,8 +17,6 @@`
`17`	`17`	`# along with this library. If not, see <https://www.gnu.org/licenses/>.`
`18`	`18`	`#`
`19`	`19`	`# *****************************************************************************`
`20`		`-`
`21`		`-`
`22`	`20`	`class Environment:`
`23`	`21`	`def __init__(self):`
`24`	`22`	`try:`