multitool 0.7.2__tar.gz → 0.9.0__tar.gz

{multitool-0.7.2 → multitool-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multitool
-Version: 0.7.2
+Version: 0.9.0
 Summary: Create and run plugin-based command-line tools.
 Author-email: Matthew Delotavo <matthew.t.delotavo@gmail.com>
 License-Expression: MIT
@@ -19,6 +19,7 @@ Requires-Dist: click>=8.1.3
 Requires-Dist: click-aliases>=1.0.1
 Requires-Dist: click-option-group>=0.5.5
 Requires-Dist: GitPython>=3.1.30
+Requires-Dist: packaging>=26.2
 Dynamic: license-file
 
 multitool
@@ -51,8 +52,7 @@ Run the example command::
         -vv \
         --enabled \
         --tag alpha \
-        --tag beta \
-        --output result.json
+        --tag beta
 
 Edit the generated source code::
 
@@ -73,8 +73,9 @@ Usage
       -h, --help     Show this message and exit.
 
     Commands:
-      plugins  Manage plugin repositories.
-      run      Run installed plugin commands.
+      bootstrap  Create the directory structure for a new Python package...
+      plugins    Manage plugin repositories.
+      run        Run installed plugin commands.
 
 ----------------
 Managing plugins
@@ -145,23 +146,45 @@ plugins directory to use it locally.
 Configuring
 ^^^^^^^^^^^
 
-Configure plugin repositories with::
+Add a plugin repository with::
 
-    multitool plugins configure -a
+    multitool plugins add https://github.com/mdelotavo/multitool-plugins.git
+
+By default, the repository name is used as the source key. To specify your own
+key::
+
+    multitool plugins add https://github.com/mdelotavo/multitool-plugins.git --key example
+
+Remove a configured plugin source by key or URL::
+
+    multitool plugins remove multitool-plugins
+
+    multitool plugins remove https://github.com/mdelotavo/multitool-plugins.git
+
+Apply configuration changes (install new plugins and update existing plugins)
+with::
+
+    multitool plugins update
+
+For bulk edits, you can edit the configuration file directly::
+
+    multitool plugins configure
 
-This opens your editor to modify the plugin configuration. Omit ``-a`` if you
-don't want changes applied automatically.
+To automatically apply configuration changes after saving and closing the file
+(install new plugins, update existing plugins, and prune removed plugins), use::
+
+    multitool plugins configure -a
 
 Example configuration::
 
     [sources]
-    mdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git
+    multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git
 
-After saving, Multitool clones each configured repository into::
+Configured repositories are cloned into::
 
     ~/.multitool/plugins/
 
-You can configure multiple repositories as long as each key is unique.
+Multiple repositories may be configured as long as each source key is unique.
 
 ^^^^^^^^^^
 Installing
@@ -169,14 +192,14 @@ Installing
 
 Install the example plugins::
 
-    echo -e '[sources]\nmdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git' >> ~/.multitool/plugins/config
+    multitool plugins add https://github.com/mdelotavo/multitool-plugins.git
 
     multitool plugins update
+
     multitool plugins show
-    multitool plugins show -n mdelotavo-multitool-plugins
-    multitool plugins show -n mdelotavo-multitool-plugins --show-commit-only
-    multitool plugins show -n mdelotavo-multitool-plugins --show-dependencies-only
-    pip3 install $(multitool plugins show -n mdelotavo-multitool-plugins --show-dependencies-only)
+    multitool plugins show -n multitool-plugins
+    multitool plugins show -n multitool-plugins --show-commit-only
+    multitool plugins show -n multitool-plugins --show-dependencies-only
 
     multitool run examples -h
 
@@ -184,18 +207,75 @@ Install the example plugins::
 Updating
 ^^^^^^^^
 
-Install new plugins and update existing ones::
+Install new plugins, update existing ones, and automatically install any Python
+dependencies declared in the Requires field of the plugin's
+multitool-info.json file::
 
     multitool plugins update
 
+Update a specific plugin only::
+
+    multitool plugins update -n PLUGIN_NAME
+
+The Requires field is where a plugin declares the Python packages it
+depends on. Any packages listed will be installed automatically when
+multitool plugins update is run. For example::
+
+  {
+    "Homepage": "",
+    "Requires": "click>=8.1.3 click-aliases>=1.0.1 click-option-group>=0.5.5 GitPython>=3.1.30",
+    "Maintainer": "",
+    "Description-en": ""
+  }
+
+If one or more dependencies could not be installed automatically, multitool
+will report the failures and display the appropriate pip command to install
+the remaining packages manually. For example::
+
+    Updating plugins
+    ----------------
+    Updating multitool-plugins... Done
+    Updating test... Skipped Git pull (not a Git repository)
+
+    Checking Python package dependencies
+    ------------------------------------
+    Checked GitPython (GitPython>=3.1.30)... 3.1.50 installed
+    Installing asdfasdfasdf... Failed
+    Checked click-aliases (click-aliases>=1.0.1)... 1.0.1 installed
+    Checked click-option-group (click-option-group>=0.5.5)... 0.5.5 installed
+    Checked click (click>=8.1.3)... 8.1.8 installed
+    Installing qwerqwerqwer>=8.1.3... Failed
+    Checked tabulate (tabulate)... 0.9.0 installed
+
+    The following dependencies could not be installed automatically:
+      asdfasdfasdf
+      qwerqwerqwer>=8.1.3
+
+    Try installing them manually:
+      /usr/bin/python3 -m pip install asdfasdfasdf qwerqwerqwer>=8.1.3
+
+You can also display a plugin's declared dependencies at any time::
+
+    multitool plugins show --name PLUGIN_NAME --show-dependencies-only
+
 ^^^^^^^
 Pruning
 ^^^^^^^
 
-Remove repositories no longer listed in the configuration::
+To uninstall a plugin repository, first remove it from the configured sources::
+
+    multitool plugins remove multitool-plugins
+
+Then remove any local repositories that are no longer configured::
 
     multitool plugins prune
 
+Alternatively, running::
+
+    multitool plugins configure -a
+
+automatically prunes repositories removed from the configuration.
+
 ^^^^^^^
 Showing
 ^^^^^^^
@@ -209,11 +289,6 @@ Or inspect a specific repository::
     multitool plugins show -n PLUGIN_NAME --show-commit-only
     multitool plugins show -n PLUGIN_NAME --show-dependencies-only
 
-If a plugin declares Python dependencies in ``multitool-info.json``, install
-them with::
-
-    pip3 install $(multitool plugins show -n PLUGIN_NAME --show-dependencies-only)
-
 ---------------
 Troubleshooting
 ---------------
@@ -224,32 +299,6 @@ If a plugin fails to install or load, check the log file::
 
 It contains installation, dependency, and Git-related errors.
 
------------
-Limitations
------------
-
-Plugin command names must be unique across all installed repositories.
-
-To avoid naming conflicts, plugin modules should follow the convention of
-including the repository owner and repository name in the command name.
-
-For example, a repository configured as::
-
-    [sources]
-    mdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git
-
-should expose commands using a unique name such as::
-
-    mdelotavo-multitool-plugins
-
-This reduces the likelihood of collisions when multiple repositories expose
-plugins with the same command name.
-
-If duplicate command names are detected, Multitool will display an error
-prompting you to delete the detected conflicting plugin repositories and, if
-applicable, remove the corresponding remote sources from your plugin
-configuration.
-
 
 .. _`click`: https://click.palletsprojects.com/
 .. _`multitool-plugins`: https://github.com/mdelotavo/multitool-plugins

{multitool-0.7.2 → multitool-0.9.0}/README.rst

@@ -28,8 +28,7 @@ Run the example command::
         -vv \
         --enabled \
         --tag alpha \
-        --tag beta \
-        --output result.json
+        --tag beta
 
 Edit the generated source code::
 
@@ -50,8 +49,9 @@ Usage
       -h, --help     Show this message and exit.
 
     Commands:
-      plugins  Manage plugin repositories.
-      run      Run installed plugin commands.
+      bootstrap  Create the directory structure for a new Python package...
+      plugins    Manage plugin repositories.
+      run        Run installed plugin commands.
 
 ----------------
 Managing plugins
@@ -122,23 +122,45 @@ plugins directory to use it locally.
 Configuring
 ^^^^^^^^^^^
 
-Configure plugin repositories with::
+Add a plugin repository with::
 
-    multitool plugins configure -a
+    multitool plugins add https://github.com/mdelotavo/multitool-plugins.git
+
+By default, the repository name is used as the source key. To specify your own
+key::
+
+    multitool plugins add https://github.com/mdelotavo/multitool-plugins.git --key example
+
+Remove a configured plugin source by key or URL::
+
+    multitool plugins remove multitool-plugins
+
+    multitool plugins remove https://github.com/mdelotavo/multitool-plugins.git
+
+Apply configuration changes (install new plugins and update existing plugins)
+with::
+
+    multitool plugins update
+
+For bulk edits, you can edit the configuration file directly::
+
+    multitool plugins configure
 
-This opens your editor to modify the plugin configuration. Omit ``-a`` if you
-don't want changes applied automatically.
+To automatically apply configuration changes after saving and closing the file
+(install new plugins, update existing plugins, and prune removed plugins), use::
+
+    multitool plugins configure -a
 
 Example configuration::
 
     [sources]
-    mdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git
+    multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git
 
-After saving, Multitool clones each configured repository into::
+Configured repositories are cloned into::
 
     ~/.multitool/plugins/
 
-You can configure multiple repositories as long as each key is unique.
+Multiple repositories may be configured as long as each source key is unique.
 
 ^^^^^^^^^^
 Installing
@@ -146,14 +168,14 @@ Installing
 
 Install the example plugins::
 
-    echo -e '[sources]\nmdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git' >> ~/.multitool/plugins/config
+    multitool plugins add https://github.com/mdelotavo/multitool-plugins.git
 
     multitool plugins update
+
     multitool plugins show
-    multitool plugins show -n mdelotavo-multitool-plugins
-    multitool plugins show -n mdelotavo-multitool-plugins --show-commit-only
-    multitool plugins show -n mdelotavo-multitool-plugins --show-dependencies-only
-    pip3 install $(multitool plugins show -n mdelotavo-multitool-plugins --show-dependencies-only)
+    multitool plugins show -n multitool-plugins
+    multitool plugins show -n multitool-plugins --show-commit-only
+    multitool plugins show -n multitool-plugins --show-dependencies-only
 
     multitool run examples -h
 
@@ -161,18 +183,75 @@ Install the example plugins::
 Updating
 ^^^^^^^^
 
-Install new plugins and update existing ones::
+Install new plugins, update existing ones, and automatically install any Python
+dependencies declared in the Requires field of the plugin's
+multitool-info.json file::
 
     multitool plugins update
 
+Update a specific plugin only::
+
+    multitool plugins update -n PLUGIN_NAME
+
+The Requires field is where a plugin declares the Python packages it
+depends on. Any packages listed will be installed automatically when
+multitool plugins update is run. For example::
+
+  {
+    "Homepage": "",
+    "Requires": "click>=8.1.3 click-aliases>=1.0.1 click-option-group>=0.5.5 GitPython>=3.1.30",
+    "Maintainer": "",
+    "Description-en": ""
+  }
+
+If one or more dependencies could not be installed automatically, multitool
+will report the failures and display the appropriate pip command to install
+the remaining packages manually. For example::
+
+    Updating plugins
+    ----------------
+    Updating multitool-plugins... Done
+    Updating test... Skipped Git pull (not a Git repository)
+
+    Checking Python package dependencies
+    ------------------------------------
+    Checked GitPython (GitPython>=3.1.30)... 3.1.50 installed
+    Installing asdfasdfasdf... Failed
+    Checked click-aliases (click-aliases>=1.0.1)... 1.0.1 installed
+    Checked click-option-group (click-option-group>=0.5.5)... 0.5.5 installed
+    Checked click (click>=8.1.3)... 8.1.8 installed
+    Installing qwerqwerqwer>=8.1.3... Failed
+    Checked tabulate (tabulate)... 0.9.0 installed
+
+    The following dependencies could not be installed automatically:
+      asdfasdfasdf
+      qwerqwerqwer>=8.1.3
+
+    Try installing them manually:
+      /usr/bin/python3 -m pip install asdfasdfasdf qwerqwerqwer>=8.1.3
+
+You can also display a plugin's declared dependencies at any time::
+
+    multitool plugins show --name PLUGIN_NAME --show-dependencies-only
+
 ^^^^^^^
 Pruning
 ^^^^^^^
 
-Remove repositories no longer listed in the configuration::
+To uninstall a plugin repository, first remove it from the configured sources::
+
+    multitool plugins remove multitool-plugins
+
+Then remove any local repositories that are no longer configured::
 
     multitool plugins prune
 
+Alternatively, running::
+
+    multitool plugins configure -a
+
+automatically prunes repositories removed from the configuration.
+
 ^^^^^^^
 Showing
 ^^^^^^^
@@ -186,11 +265,6 @@ Or inspect a specific repository::
     multitool plugins show -n PLUGIN_NAME --show-commit-only
     multitool plugins show -n PLUGIN_NAME --show-dependencies-only
 
-If a plugin declares Python dependencies in ``multitool-info.json``, install
-them with::
-
-    pip3 install $(multitool plugins show -n PLUGIN_NAME --show-dependencies-only)
-
 ---------------
 Troubleshooting
 ---------------
@@ -201,32 +275,6 @@ If a plugin fails to install or load, check the log file::
 
 It contains installation, dependency, and Git-related errors.
 
------------
-Limitations
------------
-
-Plugin command names must be unique across all installed repositories.
-
-To avoid naming conflicts, plugin modules should follow the convention of
-including the repository owner and repository name in the command name.
-
-For example, a repository configured as::
-
-    [sources]
-    mdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git
-
-should expose commands using a unique name such as::
-
-    mdelotavo-multitool-plugins
-
-This reduces the likelihood of collisions when multiple repositories expose
-plugins with the same command name.
-
-If duplicate command names are detected, Multitool will display an error
-prompting you to delete the detected conflicting plugin repositories and, if
-applicable, remove the corresponding remote sources from your plugin
-configuration.
-
 
 .. _`click`: https://click.palletsprojects.com/
 .. _`multitool-plugins`: https://github.com/mdelotavo/multitool-plugins

{multitool-0.7.2 → multitool-0.9.0}/multitool/__init__.py

@@ -1,5 +1,5 @@
 APP = "multitool"
-__version__ = "0.7.2"
+__version__ = "0.9.0"
 description = "Create and run plugin-based command-line tools."
 long_description = ("Create and run plugin-based command-line tools by dynamically loading Click commands from local or Git-managed plugin repositories.")
 

{multitool-0.7.2 → multitool-0.9.0}/multitool/__main__.py

@@ -5,10 +5,12 @@ import click
 
 from multitool import APP, MULTITOOL_LOG_FILE, MULTITOOL_PLUGINS_DIRECTORY
 from multitool import __version__ as version
+from multitool.bootstrap.commands import bootstrap
 from multitool.cls import AliasedGroup
 from multitool.exceptions import wrap_with_exception_handling
 from multitool.plugins.commands import plugins
-from multitool.utils import (configure_root_logger, for_each_file, load_plugins)
+from multitool.run.commands import run
+from multitool.utils import configure_root_logger, for_each_file, load_plugins
 
 CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
 
@@ -21,17 +23,11 @@ def cli(ctx):
     ctx.ensure_object(dict)
 
 
-@click.group(cls=AliasedGroup)
-def run():
-    """Run installed plugin commands."""
-    pass
-
-
 @wrap_with_exception_handling
 def main():
     configure_root_logger(MULTITOOL_LOG_FILE)
 
-    cli_commands = {plugins, run}
+    cli_commands = {plugins, run, bootstrap}
 
     run_commands = {}
 

multitool-0.9.0/multitool/bootstrap/commands.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+import click
+
+from multitool import console
+from multitool.silent import common_silent_options
+from multitool.utils import mkdir, touch
+from multitool.verbose import common_verbose_options
+
+PROJECT_STRUCTURE = {
+  "pyproject.toml": None,
+  "{app}": {
+    "__init__.py": None,
+    "__main__.py": None,
+    # "cls.py": None,
+    "console.py": None,
+    "exceptions.py": None,
+    "silent.py": None,
+    "utils.py": None,
+    "utils_init.py": None,
+    "verbose.py": None,
+    "submodule": {
+      "__init__.py": None,
+      "commands.py": None,
+    },
+  },
+}
+
+
+def create_structure(root: Path, structure: dict, app: str):
+    for name, children in structure.items():
+        path = root / name.format(app=app)
+
+        if children is None:
+            touch(path)
+        else:
+            mkdir(path)
+            create_structure(path, children, app)
+
+
+@click.command(help="Create the directory structure for a new Python package project.")
+@click.argument("name")
+@click.argument(
+  "directory",
+  type=click.Path(path_type=Path),
+  default=".",
+  required=False,
+)
+@common_silent_options
+@common_verbose_options
+def bootstrap(silent, verbose, name, directory):
+    root = directory / name
+    mkdir(root)
+
+    create_structure(root, PROJECT_STRUCTURE, name)
+
+    console.echo(f"Created project: {root}")

{multitool-0.7.2 → multitool-0.9.0}/multitool/console.py

@@ -1,6 +1,6 @@
-from dataclasses import dataclass, fields, replace
 import builtins
 import sys
+from dataclasses import dataclass, fields, replace
 
 
 @dataclass(slots=True)