Metadata-Version: 2.4
Name: danbyte-myplugin
Version: 0.1.0
Summary: A Danbyte plugin.
Project-URL: Homepage, https://github.com/danbyte-net/danbyte
Project-URL: Documentation, https://github.com/danbyte-net/danbyte/blob/main/docs/architecture/plugins.md
Author-email: Your Name <you@example.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: danbyte,dcim,ipam,plugin
Classifier: Framework :: Django
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Danbyte plugin template

A starter for building a [Danbyte](https://github.com/danbyte-net/danbyte)
plugin. Click **“Use this template”** (or clone it), rename a few things, and
you have a working plugin that adds a model, a REST API, a monitoring check
kind, an automation provider, and server-driven UI — with **no changes to
Danbyte core and no frontend build**.

> Danbyte plugins are **trusted, in-process** Python packages (NetBox-style):
> an operator installs the package, lists it in the `PLUGINS` setting, and
> restarts. See the full guide:
> [Danbyte docs → Architecture → Plugins](https://github.com/danbyte-net/danbyte/blob/main/docs/architecture/plugins.md).

---

## What's in here

```
danbyte_myplugin/
├── apps.py            # DanbytePluginConfig — plugin metadata
├── danbyte_plugin.py  # THE registration entry point (autodiscovered)
├── models.py          # a sample tenant-scoped model (Gadget)
├── serializers.py     # DRF serializer (tags + custom fields)
├── viewsets.py        # tenant-scoped, RBAC default-closed CRUD
├── api_urls.py        # mounted at /api/plugins/<slug>/
├── checks.py          # a sample monitoring check kind
└── migrations/
pyproject.toml         # packaging (hatchling)
.github/workflows/     # publish to PyPI on release (Trusted Publishing)
```

## Rename it (once)

Pick a name — e.g. `danbyte_acme`. Then:

1. Rename the `danbyte_myplugin/` folder → `danbyte_acme/`.
2. In `pyproject.toml`: `name = "danbyte-acme"` and `packages = ["danbyte_acme"]`.
3. In `apps.py`: `name = "danbyte_acme"`, and pick a `slug` (e.g. `acme`).
4. Search-and-replace `myplugin` → `acme` and `danbyte_myplugin` → `danbyte_acme`
   across the package (slugs, URLs, the migration's model, `audit_type`).
5. Rename the sample `Gadget` model to yours (or delete it and add your own).

## Develop against a Danbyte checkout

Your plugin imports from the host (`core`, `api`, `auth_api`, `plugins`,
`danbyte_checks`), so develop it inside a Danbyte environment:

```bash
# in your Danbyte checkout, with its virtualenv active
pip install -e /path/to/danbyte-acme          # editable install
echo 'PLUGINS=danbyte_acme' >> .env           # enable it
python manage.py makemigrations danbyte_acme  # generate real migrations
python manage.py migrate
python manage.py runserver                    # (or restart your services)
```

Open **Settings → Deployment → Plugins & services** — your plugin appears as
`loaded`, and its nav item + pages show up (subject to RBAC). Grant yourself the
object-type permission (e.g. `gadget`) to see and edit rows.

## What you can register (`danbyte_plugin.py`)

| You want… | Call / mixin |
|---|---|
| A model in RBAC + import/export + eventing | `register_object_type("danbyte_acme.Gadget", "Gadgets", "Plugins")` |
| Custom fields on it | mix in `core.models.CustomFieldsMixin` |
| Tags on it | mix in `core.models.TaggableMixin` |
| It targetable by object-reference custom fields | `register_reference_model(ReferenceModel(...))` |
| Change-log / audit | `register_audited_model("danbyte_acme.Gadget")` |
| A REST API | ship `api_urls.py` (auto-mounted at `/api/plugins/<slug>/`) |
| An automation runner | `register_automation_provider(kind, runner)` |
| An import source / notification channel | `register_import_source(...)` / `register_notification_channel(...)` |
| A monitoring check kind | `@danbyte_checks.base.register` on a `Checker` |
| Sidebar nav / pages / dashboard panels | `register_nav_item / register_page / register_dashboard_panel` |

**Rules that matter**

- `apps.py` and `__init__.py` must be **import-safe** — no model imports at the
  top level (Danbyte reads your metadata before the app registry exists).
- Every model uses a **UUID primary key** and a **`tenant` FK**; scope all
  querysets to the active tenant (the `TenantScopedViewSet` base does this).
- New endpoints are **default-closed** — registering the object type is what
  makes yours require a `<model>.*` grant. Never trust a client-supplied id to
  belong to the current tenant.

## Publish to PyPI

The included workflow publishes on a GitHub Release using **Trusted Publishing**
(OIDC — no token stored):

1. On PyPI: create the project (or reserve the name), then **Publishing → add a
   GitHub publisher**: owner `your-org`, repo `danbyte-acme`, workflow
   `publish.yml`, environment `pypi`.
2. In GitHub: create an environment named `pypi`.
3. Cut a GitHub Release (tag e.g. `v0.1.0`). The workflow builds and uploads.

Prefer a token? Set a `PYPI_API_TOKEN` repo secret and pass it to the publish
step (see the comment in `.github/workflows/publish.yml`). **Never commit a
token.**

Users then install your plugin with `pip install danbyte-acme`, add it to
`PLUGINS`, and apply (migrate + restart).

## License

Apache-2.0, matching Danbyte. Change it to suit your plugin.
