From c5f5452181a32f8781084a8afaaf2b47a155a3e0 Mon Sep 17 00:00:00 2001 From: MrTango Date: Tue, 7 Apr 2026 10:25:15 -0700 Subject: [PATCH 01/14] Add shell completion command and update completion docs Replace the outdated Click 7.x plonecli_autocomplete.sh with a built-in `plonecli completion` command that generates correct Click 8.0+ completion scripts for bash, zsh, and fish. Supports --install flag to automatically append the activation line to the user's shell config file. Update README.md and docs/installation.md with shell completion setup instructions, including a developer workflow section for using completion with editable installs. Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGES.rst | 53 +++- README.md | 431 +++++++++++++++++++++++++++ README.rst | 359 +++++++++-------------- docs/installation.md | 81 +++++ plonecli/__init__.py | 10 +- plonecli/cli.py | 438 ++++++++++++++++------------ plonecli/config.py | 127 ++++++++ plonecli/configure_mrbob.py | 233 --------------- plonecli/configure_mrbob/.mrbob.ini | 64 ---- plonecli/exceptions.py | 14 +- plonecli/plone_versions.py | 122 ++++++++ plonecli/project.py | 99 +++++++ plonecli/registry.py | 242 ++++++--------- plonecli/templates.py | 205 +++++++++++++ plonecli/updater.py | 98 +++++++ plonecli_autocomplete.sh | 8 - pyproject.toml | 71 +++++ setup.cfg | 70 ----- setup.py | 40 --- tests/conftest.py | 12 +- tests/test_config.py | 152 ++++++++++ tests/test_configure_mrbob.py | 226 -------------- tests/test_plonecli.py | 364 +++++++++++------------ tests/test_project.py | 98 +++++++ tests/test_registry.py | 228 ++++++++------- tests/test_templates.py | 136 +++++++++ tests/test_updater.py | 95 ++++++ tox.ini | 124 +------- 28 files changed, 2567 insertions(+), 1633 deletions(-) create mode 100644 README.md create mode 100644 docs/installation.md create mode 100644 plonecli/config.py delete mode 100644 plonecli/configure_mrbob.py delete mode 100644 plonecli/configure_mrbob/.mrbob.ini create mode 100644 plonecli/plone_versions.py create mode 100644 plonecli/project.py create mode 100644 plonecli/templates.py create mode 100644 plonecli/updater.py delete mode 100755 plonecli_autocomplete.sh create mode 100644 pyproject.toml delete mode 100644 setup.cfg delete mode 100644 setup.py create mode 100644 tests/test_config.py delete mode 100644 tests/test_configure_mrbob.py create mode 100644 tests/test_project.py create mode 100644 tests/test_templates.py create mode 100644 tests/test_updater.py diff --git a/CHANGES.rst b/CHANGES.rst index 4efcc0b..5961676 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,14 +1,55 @@ History ======= -2.6 (unreleased) ----------------- +3.0.0a1 (unreleased) +-------------------- -- Support only python 3.11 - 3.14 - [erral] +Breaking changes: -- Require setuptools < 82.0.0 - [erral] +- Major rewrite: replaced mr.bob/bobtemplates.plone with copier-templates. + Templates are now managed as a local git clone at + ``~/.copier-templates/plone-copier-templates``. + [MrTango] + +- Removed buildout-related commands: ``build``, ``buildout``, + ``requirements``, ``venv``/``virtualenv``. + [MrTango] + +- Replaced ``~/.mrbob`` config with ``~/.plonecli/config.toml``. + Migration from old config is offered on first run. + [MrTango] + +New features: + +- New ``update`` command to update copier-templates and check PyPI for + plonecli updates. + [MrTango] + +- New ``setup`` command to run zope-setup inside an existing backend_addon. + [MrTango] + +- ``serve``, ``test``, ``debug`` now delegate to invoke tasks generated by + templates (``uv run invoke start/test/debug``). + [MrTango] + +- Default Plone version is fetched from ``dist.plone.org/release/`` and + cached for 24 hours. + [MrTango] + +- Environment variable overrides for template repo configuration: + ``PLONECLI_TEMPLATES_REPO_URL``, ``PLONECLI_TEMPLATES_BRANCH``, + ``PLONECLI_TEMPLATES_DIR``. + [MrTango] + +- Periodic PyPI update check (every 24 hours) with non-intrusive notification. + [MrTango] + +- Primary installation method is now ``uv tool install plonecli``. Also + supports uvx, venv, and pipx. + [MrTango] + +- Requires Python >= 3.11. + [MrTango] 2.5 (2022-11-03) diff --git a/README.md b/README.md new file mode 100644 index 0000000..e9838fd --- /dev/null +++ b/README.md @@ -0,0 +1,431 @@ +[![CI](https://github.com/plone/plonecli/actions/workflows/python-package.yml/badge.svg)](https://github.com/plone/plonecli/actions/workflows/python-package.yml) +[![PyPI](https://img.shields.io/pypi/v/plonecli.svg)](https://pypi.python.org/pypi/plonecli/) + +# Plone CLI + +![Plone CLI Logo](https://raw.githubusercontent.com/plone/plonecli/master/docs/plone_cli_logo.svg) + +**A Plone CLI for creating Plone packages** + +The Plone CLI is meant for developing Plone packages. It uses [copier](https://copier.readthedocs.io/) templates to scaffold Plone backend addons, Zope project setups, and add features like content types, behaviors, and REST API services. + + +## Installation + +### UV Tool (Recommended) + +The recommended way to install plonecli is as a UV tool, which makes it available globally: + +```shell +uv tool install plonecli +``` + +To upgrade: + +```shell +uv tool upgrade plonecli +``` + +### Run Without Installing (uvx) + +You can run plonecli without installing it using `uvx`: + +```shell +uvx plonecli create addon my.addon +``` + +### In a Virtual Environment + +```shell +uv venv +source .venv/bin/activate +uv pip install plonecli +``` + +### With pipx + +```shell +pipx install plonecli +``` + + +## Shell Completion + +plonecli supports tab-completion for commands and template names in **bash**, **zsh**, and **fish**. + +### Quick Install + +```shell +plonecli completion --install +``` + +This auto-detects your shell and appends the activation line to your `~/.bashrc`, `~/.zshrc`, or fish completions directory. Restart your shell afterward. + +### Manual Setup + +If you prefer to set it up yourself: + +**Bash** (add to `~/.bashrc`): +```shell +eval "$(_PLONECLI_COMPLETE=bash_source plonecli)" +``` + +**Zsh** (add to `~/.zshrc`): +```shell +eval "$(_PLONECLI_COMPLETE=zsh_source plonecli)" +``` + +**Fish** (add to `~/.config/fish/completions/plonecli.fish`): +```shell +env _PLONECLI_COMPLETE=fish_source plonecli | source +``` + +### Faster Startup (Optional) + +The `eval` approach generates the completion script on every shell start. For faster startup, save it to a file: + +```shell +# Generate once +_PLONECLI_COMPLETE=bash_source plonecli > ~/.plonecli-complete.bash + +# Then source from your ~/.bashrc instead of eval +source ~/.plonecli-complete.bash +``` + +### Developer Shell Completion + +When developing plonecli or copier-templates from a git checkout, the installed `plonecli` entry point may not reflect your local changes. Use `uv run` to run the development version, but note that tab-completion only works for the installed `plonecli` command, not `uv run plonecli`. + +For development, temporarily install the package in editable mode so that the `plonecli` entry point uses your local code: + +```shell +uv tool install --editable . +``` + +This makes the global `plonecli` command point to your working copy, and shell completion works normally. When done, reinstall the released version: + +```shell +uv tool install plonecli +``` + + +## First Run + +On first run, plonecli will clone the copier-templates repository to `~/.copier-templates/plone-copier-templates`. + +Configure your author defaults: + +```shell +plonecli config +``` + +This creates `~/.plonecli/config.toml` with your settings. + + +## Usage + +### Available Commands + +```shell +plonecli --help + +Commands: + add Add features to your existing Plone package + config Configure plonecli global settings + create Create a new Plone package + debug Start the Plone instance in debug mode + serve Start the Plone instance + setup Run zope-setup inside an existing backend_addon + test Run the tests in your package + update Update copier-templates and check for plonecli updates + +Options: + -l, --list-templates List available templates + -V, --versions Show version information + -h, --help Show this message and exit. +``` + + +### Creating a Plone Add-on + +```shell +plonecli create addon collective.todo +``` + +Or create a Zope project setup: + +```shell +plonecli create zope-setup my-project +``` + + +### Adding Features to Your Plone Add-on + +Inside your addon directory, you can add features through subtemplates: + +```shell +cd collective.todo + +plonecli add content_type +plonecli add behavior +plonecli add restapi_service +``` + + +### Setting Up a Zope Project + +Inside an existing addon, set up the Zope project infrastructure: + +```shell +cd collective.todo +plonecli setup +``` + + +### Running Your Application + +```shell +plonecli serve +``` + +This delegates to `uv run invoke start` which is configured by the project templates. + + +### Running Tests + +```shell +plonecli test +``` + +With verbose output: + +```shell +plonecli test --verbose +``` + + +### Debug Mode + +```shell +plonecli debug +``` + + +### Updating Templates + +```shell +plonecli update +``` + +This pulls the latest copier-templates and checks PyPI for plonecli updates. + + +### Listing Templates + +```shell +plonecli -l + +Available templates: + + Project templates (plonecli create