Metadata-Version: 2.4
Name: qgis-manage
Version: 0.6.0
Summary: A modern CLI for managing QGIS plugin development, deployment, and packaging.
Project-URL: Homepage, https://github.com/geociencio/qgis-plugin-manager
Project-URL: Repository, https://github.com/geociencio/qgis-plugin-manager
Project-URL: Issues, https://github.com/geociencio/qgis-plugin-manager/issues
Author-email: Juan M Bernales <juanbernales@gmail.com>
License: GPL-2.0-or-later
License-File: LICENSE
Keywords: cli,development,manager,plugin,qgis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: mypy>=1.19.1; extra == 'dev'
Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
Requires-Dist: ruff>=0.14.10; extra == 'dev'
Requires-Dist: types-setuptools>=80.9.0.20251223; extra == 'dev'
Description-Content-Type: text/markdown

# QGIS Plugin Manager

[![CI](https://github.com/geociencio/qgis-plugin-manager/actions/workflows/main.yml/badge.svg)](https://github.com/geociencio/qgis-plugin-manager/actions/workflows/main.yml)
[![License: GPL v2+](https://img.shields.io/badge/License-GPL%20v2%2B-blue.svg)](LICENSE)
[![Code Quality](https://img.shields.io/badge/Code%20Quality-66.6%2F100-brightgreen)](analysis_results/PROJECT_SUMMARY.md)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

A professional CLI for managing QGIS plugin development, deployment, and packaging. Modernized for Python 3.10+ and `uv`.

> [!IMPORTANT]
> **This is a CLI tool, not a QGIS plugin**
>
> This project is a **command-line tool** for managing QGIS plugin development. It should be installed as a Python package using `uv` or `pip`, **not** as a plugin in QGIS.
>
> - ✅ Use it to develop and deploy QGIS plugins
> - ❌ Do NOT install it as a plugin in QGIS

## 🚀 Features

- **Dynamic Deployment**: Automatically detects your QGIS profile directory (Linux, Windows, macOS).
- **Smart Discovery**: Reads `metadata.txt` to identify your plugin and automatically selects source files.
- **Safety First**: Automatically creates timestamped backups of your plugin folder before every deployment.
- **Qt & Documentation Integration**: Compiles `.qrc` resources, `.ts` translations, and Sphinx documentation automatically.
- **Clean Workflow**: Removes `__pycache__` and artifacts recursively.
- **Interactive Mode**: Option for step-by-step confirmation of critical steps.
- **Customizable Hooks**: Support for shell commands before and after deployment.
- **Persistent Config**: Global and project-level settings management.

## 📦 Installation

Install system-wide as a tool using `uv`:

```bash
uv tool install git+https://github.com/geociencio/qgis-plugin-manager.git
```

Or add it to your project's development dependencies:

```bash
uv add --group dev qgis-plugin-manager @ git+https://github.com/geociencio/qgis-plugin-manager.git
```

## 🛠️ Usage

From your plugin project root:

```bash
# Initialize a new plugin project scaffolding
qgis-manage init "My Plugin" --author "Juan" --email "juan@example.com" --template processing

# Install external dependencies to local libs/ folder
qgis-manage install-deps

# Deploy to QGIS profile (with automatic backup and compilation)
qgis-manage deploy

# Deploy to a specific profile
qgis-manage deploy --profile production

# Deploy with interactive step-by-step confirmation
qgis-manage deploy --interactive

# Create distributable ZIP package (automatically installs dependencies)
qgis-manage package

# Create package without dev files
qgis-manage package --output ./releases

# Run QGIS Plugin Analyzer on the project
qgis-manage analyze

# Validate metadata.txt compliance
qgis-manage validate --strict

# Compile all resources, translations, and documentation
qgis-manage compile

# Compile only documentation
qgis-manage compile --type docs

# Clean Python artifacts and build files
qgis-manage clean
```

## ⚙️ Configuration

### Robust Exclusions (`.qgisignore`)
You can control which files are excluded from deployment and packaging by creating a `.qgisignore` file in your project root. It supports gitignore-style patterns:

```text
# Exclude CSV data files
data/*.csv

# Exclude specific folders
temp/
tests/data/

# Recursive match (anywhere in the project)
debug.log
```

### Dependency Management
Define your plugin's external Python dependencies in `pyproject.toml`:

```toml
[tool.qgis-manager]
dependencies = [
    "requests",
    "six",
    "pandas"
]
```
Running `qgis-manage install-deps` will install these into a local `libs/` folder. Remember to add this folder to `sys.path` in your plugin's `__init__.py`.

## 📖 Documentation

- [CHANGELOG.md](CHANGELOG.md): History of changes and releases.
- [RULES.md](RULES.md): Coding standards and project rules.

## 📄 License

GPL-2.0-or-later
