newrelic-as-code 0.1.0__tar.gz

newrelic_as_code-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+.idea/
+.vscode/
+
+# Introspected NerdGraph schema for IDE GraphQL support (see graphql.config.yaml);
+# large and regenerated locally, never committed.
+nerdgraph.schema.graphql

newrelic_as_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilia Peterov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

newrelic_as_code-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: newrelic-as-code
+Version: 0.1.0
+Summary: Define New Relic dashboards as code and reconcile them to an account
+Project-URL: Homepage, https://github.com/ipeterov/newrelic-as-code
+Project-URL: Repository, https://github.com/ipeterov/newrelic-as-code
+Author-email: Ilia Peterov <ipeterov1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.26
+Description-Content-Type: text/markdown
+
+# newrelic-as-code
+
+Define New Relic dashboards as code and reconcile them to an account.
+
+New Relic resources should be defined in version-controlled Python and
+reconciled to the account on deploy, never hand-edited in the UI. You describe
+dashboards as pydantic models and the library handles finding the resources it
+manages, creating/updating/deleting them to match your declared set, and
+refusing to clobber anything it didn't create.
+
+Reconcile is safe by design:
+
+- **Managed by tag.** The library only touches dashboards carrying its
+  `managed-by` tag. A same-named dashboard without the tag is refused, never
+  overwritten — so hand-built dashboards are safe.
+- **Orphan cleanup.** A managed dashboard that's no longer in your declared set
+  is deleted.
+- **Dry run.** Pass `dry_run=True` to print what would change without touching
+  the account.
+
+## Installation
+
+```bash
+pip install newrelic-as-code
+```
+
+## Usage
+
+```python
+from newrelic_as_code import (
+    Dashboard,
+    NewRelicUpdater,
+    NrqlQuery,
+    Page,
+    Widget,
+    EU_ENDPOINT,
+)
+
+dashboard = Dashboard(
+    name='My service',
+    pages=[
+        Page(
+            name='Overview',
+            widgets=[
+                Widget(
+                    title='Throughput',
+                    visualization='viz.line',
+                    column=1,
+                    row=1,
+                    queries=[
+                        NrqlQuery(
+                            query='SELECT rate(count(*), 1 minute) '
+                            'FROM Transaction TIMESERIES',
+                        ),
+                    ],
+                ),
+            ],
+        ),
+    ],
+)
+
+updater = NewRelicUpdater(
+    account_id=1234567,
+    api_key='NRAK-...',
+    # Defaults to the US region; pass EU_ENDPOINT (or any full URL) for others.
+    endpoint=EU_ENDPOINT,
+    # The tag that marks dashboards this tool owns. Choose a value unique to your
+    # deployment so several deployments can coexist in one account.
+    managed_tag_value='my-service-deploy',
+)
+updater.sync([dashboard])
+```
+
+## Notes
+
+- **Account id.** `account_id` is the account dashboards are created in, and is
+  injected into any `NrqlQuery` that doesn't set its own `account_ids`. Set
+  `account_ids` on a query explicitly to query across (or a different) account.
+- **`raw_configuration`.** `Widget.raw_configuration` is merged into New Relic's
+  `rawConfiguration` verbatim, so any chart option (units, colors, markers,
+  thresholds, yAxis, gauge settings, …) is available without the library
+  modelling it.
+- **Variables.** Dashboard-level template variables are supported via the
+  `Variable` model and `Dashboard(variables=[...])`.
+- **No builder.** The library's surface is the plain
+  `Dashboard`/`Page`/`Widget`/`NrqlQuery`/`Variable` model tree — you construct
+  those directly. Any layout/composition helpers (grid math, managed banners)
+  belong in your own code, since they're specific to how you lay dashboards out.
+- **Extensible reconcile.** `sync()` reconciles dashboards today. The reconcile
+  core (find-by-managed-tag → create/update/delete-orphaned → refuse-unmanaged →
+  dry-run) is resource-agnostic, so alert policies/conditions can be added as
+  additional resource types later without reshaping it.
+
+## License
+
+MIT
+
+---
+
+<sub>Not affiliated with or endorsed by New Relic, Inc. "New Relic" is a
+trademark of New Relic, Inc.</sub>

newrelic_as_code-0.1.0/README.md

@@ -0,0 +1,101 @@
+# newrelic-as-code
+
+Define New Relic dashboards as code and reconcile them to an account.
+
+New Relic resources should be defined in version-controlled Python and
+reconciled to the account on deploy, never hand-edited in the UI. You describe
+dashboards as pydantic models and the library handles finding the resources it
+manages, creating/updating/deleting them to match your declared set, and
+refusing to clobber anything it didn't create.
+
+Reconcile is safe by design:
+
+- **Managed by tag.** The library only touches dashboards carrying its
+  `managed-by` tag. A same-named dashboard without the tag is refused, never
+  overwritten — so hand-built dashboards are safe.
+- **Orphan cleanup.** A managed dashboard that's no longer in your declared set
+  is deleted.
+- **Dry run.** Pass `dry_run=True` to print what would change without touching
+  the account.
+
+## Installation
+
+```bash
+pip install newrelic-as-code
+```
+
+## Usage
+
+```python
+from newrelic_as_code import (
+    Dashboard,
+    NewRelicUpdater,
+    NrqlQuery,
+    Page,
+    Widget,
+    EU_ENDPOINT,
+)
+
+dashboard = Dashboard(
+    name='My service',
+    pages=[
+        Page(
+            name='Overview',
+            widgets=[
+                Widget(
+                    title='Throughput',
+                    visualization='viz.line',
+                    column=1,
+                    row=1,
+                    queries=[
+                        NrqlQuery(
+                            query='SELECT rate(count(*), 1 minute) '
+                            'FROM Transaction TIMESERIES',
+                        ),
+                    ],
+                ),
+            ],
+        ),
+    ],
+)
+
+updater = NewRelicUpdater(
+    account_id=1234567,
+    api_key='NRAK-...',
+    # Defaults to the US region; pass EU_ENDPOINT (or any full URL) for others.
+    endpoint=EU_ENDPOINT,
+    # The tag that marks dashboards this tool owns. Choose a value unique to your
+    # deployment so several deployments can coexist in one account.
+    managed_tag_value='my-service-deploy',
+)
+updater.sync([dashboard])
+```
+
+## Notes
+
+- **Account id.** `account_id` is the account dashboards are created in, and is
+  injected into any `NrqlQuery` that doesn't set its own `account_ids`. Set
+  `account_ids` on a query explicitly to query across (or a different) account.
+- **`raw_configuration`.** `Widget.raw_configuration` is merged into New Relic's
+  `rawConfiguration` verbatim, so any chart option (units, colors, markers,
+  thresholds, yAxis, gauge settings, …) is available without the library
+  modelling it.
+- **Variables.** Dashboard-level template variables are supported via the
+  `Variable` model and `Dashboard(variables=[...])`.
+- **No builder.** The library's surface is the plain
+  `Dashboard`/`Page`/`Widget`/`NrqlQuery`/`Variable` model tree — you construct
+  those directly. Any layout/composition helpers (grid math, managed banners)
+  belong in your own code, since they're specific to how you lay dashboards out.
+- **Extensible reconcile.** `sync()` reconciles dashboards today. The reconcile
+  core (find-by-managed-tag → create/update/delete-orphaned → refuse-unmanaged →
+  dry-run) is resource-agnostic, so alert policies/conditions can be added as
+  additional resource types later without reshaping it.
+
+## License
+
+MIT
+
+---
+
+<sub>Not affiliated with or endorsed by New Relic, Inc. "New Relic" is a
+trademark of New Relic, Inc.</sub>

newrelic_as_code-0.1.0/newrelic_as_code/__init__.py

@@ -0,0 +1,36 @@
+"""Define New Relic dashboards as code and reconcile them to an account."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import (
+    EU_ENDPOINT,
+    US_ENDPOINT,
+    NerdGraphClient,
+    NewRelicUpdaterError,
+)
+from .models import Dashboard, NrqlQuery, Page, Variable, Visualization, Widget
+from .updater import NewRelicUpdater
+from .utils import echo
+
+
+try:
+    # pyproject.toml is the single source of truth; read it from the installed
+    # package metadata rather than duplicating the number here.
+    __version__ = version("newrelic-as-code")
+except PackageNotFoundError:  # not installed (e.g. running from a source tree)
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "EU_ENDPOINT",
+    "US_ENDPOINT",
+    "Dashboard",
+    "NerdGraphClient",
+    "NewRelicUpdater",
+    "NewRelicUpdaterError",
+    "NrqlQuery",
+    "Page",
+    "Variable",
+    "Visualization",
+    "Widget",
+    "echo",
+]

newrelic_as_code-0.1.0/newrelic_as_code/client.py

@@ -0,0 +1,67 @@
+"""
+Thin New Relic NerdGraph API transport.
+
+``NerdGraphClient`` wraps a single ``requests`` session with retry/backoff and a
+dry-run gate. It knows nothing about dashboards or reconcile logic — it just
+POSTs GraphQL and reports what a mutation would do. The reconcile logic lives in
+``updater.py`` and drives this client.
+"""
+
+from collections.abc import Callable
+
+import requests
+from requests.adapters import HTTPAdapter, Retry
+
+from .utils import echo
+
+
+# Region NerdGraph endpoints. Default is US; the EU data center uses a separate
+# host. Pass a full URL to ``NewRelicUpdater(endpoint=...)`` for anything else.
+US_ENDPOINT = "https://api.newrelic.com/graphql"
+EU_ENDPOINT = "https://api.eu.newrelic.com/graphql"
+
+
+class NewRelicUpdaterError(Exception):
+    """Raised when a NerdGraph call fails or the live state is ambiguous."""
+
+
+class NerdGraphClient:
+    """Thin New Relic NerdGraph API client with a dry-run gate."""
+
+    def __init__(self, api_key: str, endpoint: str = US_ENDPOINT, dry_run: bool = False):
+        self.api_key = api_key
+        self.endpoint = endpoint
+        self.dry_run = dry_run
+        # NerdGraph occasionally responds slowly or with a transient 5xx. Retry
+        # with backoff so a blip doesn't fail the run. NerdGraph mutations are
+        # idempotent for us (create/update/delete by name+tag), so retrying a
+        # POST is safe.
+        self.session = requests.Session()
+        retry = Retry(
+            total=4,
+            backoff_factor=2,  # 0s, 2s, 4s, 8s between attempts
+            status_forcelist=(429, 500, 502, 503, 504),
+            allowed_methods=frozenset({"POST"}),
+        )
+        self.session.mount("https://", HTTPAdapter(max_retries=retry))
+
+    def call(self, query: str, variables: dict) -> dict:
+        response = self.session.post(
+            self.endpoint,
+            json={"query": query, "variables": variables},
+            headers={"API-Key": self.api_key},
+            timeout=30,
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if payload.get("errors"):
+            raise NewRelicUpdaterError(f"NerdGraph errors: {payload['errors']}")
+        return payload["data"]
+
+    def mutate(self, action: str, do: Callable[[], object]) -> object | None:
+        """Run a mutation, or just print what it would do in dry-run mode."""
+        if self.dry_run:
+            echo(f"Would {action}")
+            return None
+        echo(action[0].upper() + action[1:])
+        return do()

newrelic_as_code-0.1.0/newrelic_as_code/models.py

@@ -0,0 +1,127 @@
+"""
+New Relic dashboards as code.
+
+Typed pydantic models that each render to the JSON shape the New Relic
+NerdGraph API expects via an ``as_nr_dict()`` method. Compose dashboards
+declaratively and reconcile them with ``NewRelicUpdater``.
+
+NerdGraph dashboard input reference:
+https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-dashboards/
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+Visualization = Literal[
+    "viz.line",
+    "viz.area",
+    "viz.bar",
+    "viz.pie",
+    "viz.table",
+    "viz.billboard",
+    "viz.gauge",
+    "viz.markdown",
+]
+
+
+class NrqlQuery(BaseModel):
+    query: str
+    # Accounts this query runs against. Leave empty to let ``NewRelicUpdater``
+    # fill in its own account id at reconcile time; set it explicitly to query
+    # across accounts (or a different account than the one you reconcile to).
+    account_ids: list[int] = Field(default_factory=list)
+
+    def as_nr_dict(self) -> dict:
+        return {
+            "accountIds": self.account_ids,
+            "query": self.query,
+        }
+
+
+class Widget(BaseModel):
+    title: str
+    visualization: Visualization
+    queries: list[NrqlQuery]
+    column: int
+    row: int
+    width: int = 4
+    height: int = 3
+    # Extra keys merged into rawConfiguration (units, colors, markers, yAxis,
+    # gaugeSettings, ...). Kept as a free dict so we don't have to model every
+    # New Relic chart option.
+    raw_configuration: dict = Field(default_factory=dict)
+
+    def as_nr_dict(self) -> dict:
+        raw: dict = dict(self.raw_configuration)
+        # Query-backed widgets carry nrqlQueries; query-less widgets (e.g.
+        # markdown, which uses `text`) must not emit an empty nrqlQueries list.
+        if self.queries:
+            raw = {"nrqlQueries": [q.as_nr_dict() for q in self.queries], **raw}
+        return {
+            "title": self.title,
+            "layout": {
+                "column": self.column,
+                "row": self.row,
+                "width": self.width,
+                "height": self.height,
+            },
+            "linkedEntityGuids": None,
+            "visualization": {"id": self.visualization},
+            "rawConfiguration": raw,
+        }
+
+
+class Variable(BaseModel):
+    name: str
+    title: str
+    values: list[str]
+    default: str
+    replacement_strategy: Literal["DEFAULT", "STRING", "NUMBER", "IDENTIFIER"] = "STRING"
+
+    def as_nr_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "title": self.title,
+            "type": "ENUM",
+            "isMultiSelection": False,
+            "replacementStrategy": self.replacement_strategy,
+            "items": [{"title": None, "value": v} for v in self.values],
+            "defaultValues": [{"value": {"string": self.default}}],
+            "nrqlQuery": None,
+            "options": {"hiddenOnVariablesBar": False, "excluded": False},
+        }
+
+
+class Page(BaseModel):
+    name: str
+    widgets: list[Widget]
+    description: str | None = None
+
+    def as_nr_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "widgets": [w.as_nr_dict() for w in self.widgets],
+        }
+
+
+class Dashboard(BaseModel):
+    name: str
+    pages: list[Page]
+    description: str | None = None
+    variables: list[Variable] = Field(default_factory=list)
+    permissions: Literal["PRIVATE", "PUBLIC_READ_ONLY", "PUBLIC_READ_WRITE"] = "PUBLIC_READ_WRITE"
+
+    def as_nr_dict(self) -> dict:
+        """Render to the ``DashboardInput`` shape for dashboardCreate/dashboardUpdate."""
+        result: dict = {
+            "name": self.name,
+            "description": self.description,
+            "permissions": self.permissions,
+            "pages": [p.as_nr_dict() for p in self.pages],
+        }
+        if self.variables:
+            result["variables"] = [v.as_nr_dict() for v in self.variables]
+        return result

newrelic_as_code-0.1.0/newrelic_as_code/updater.py

@@ -0,0 +1,264 @@
+"""
+Reconciles New Relic with resource definitions in code.
+
+Config lives in code; the live state in the New Relic account is inspected, then
+resources are created/updated/deleted to match. New Relic itself is the state
+store — managed entities are found by a ``managed-by`` tag, so there is nothing
+to persist between runs.
+
+The thin API transport is ``NerdGraphClient`` (see ``client.py``);
+``NewRelicUpdater.sync()`` reconciles everything on top of it. The reconcile
+core (``_reconcile``) is resource-agnostic:
+find-by-managed-tag, create/update/delete-orphaned, refuse-to-clobber-unmanaged,
+dry-run. Dashboards use it today; alert policies/conditions can be added as more
+``sync_*`` steps that call the same core with alert-specific find/create/update/
+delete callables — without reshaping the logic here.
+"""
+
+from collections.abc import Callable
+
+from .client import US_ENDPOINT, NerdGraphClient, NewRelicUpdaterError
+from .models import Dashboard
+from .utils import echo
+
+
+DEFAULT_MANAGED_TAG_KEY = "managed-by"
+
+
+class NewRelicUpdater:
+    """Reconciles New Relic with the code definitions.
+
+    ``sync()`` is the single entry point. It reconciles dashboards today; alert
+    policies/conditions can be added as more ``_sync_*`` steps that reuse
+    ``_reconcile``.
+    """
+
+    def __init__(
+        self,
+        account_id: int,
+        api_key: str,
+        endpoint: str = US_ENDPOINT,
+        managed_tag_key: str = DEFAULT_MANAGED_TAG_KEY,
+        managed_tag_value: str = "newrelic-as-code",
+        dry_run: bool = False,
+    ):
+        self.account_id = account_id
+        self.managed_tag_key = managed_tag_key
+        self.managed_tag_value = managed_tag_value
+        self.client = NerdGraphClient(api_key, endpoint, dry_run)
+
+    def sync(self, dashboards: list[Dashboard]) -> None:
+        if self.client.dry_run:
+            echo("Dry run — no changes will be applied")
+        self._sync_dashboards(dashboards)
+        echo("OK")
+
+    # -- Generic reconcile core ----------------------------------------------
+
+    def _reconcile(
+        self,
+        kind: str,
+        entity_type: str,
+        defined: dict[str, object],
+        create: Callable[[object], None],
+        update: Callable[[str, object], None],
+        delete: Callable[[str], None],
+    ) -> None:
+        """Reconcile a set of managed resources of one ``entity_type``.
+
+        ``defined`` maps resource name -> the resource object to apply. For each,
+        we look up the existing managed entity (refusing to clobber a same-named
+        unmanaged one), then create or update. Finally, any managed entity of
+        this type no longer in ``defined`` is deleted as orphaned.
+
+        Resource-agnostic: dashboards pass their find/create/update/delete;
+        alerts can pass their own without reshaping this logic.
+        """
+        for name, resource in defined.items():
+            existing = self._find_entity(name, entity_type)
+            if existing:
+                self.client.mutate(
+                    f"update “{name}”",
+                    lambda r=resource, g=existing["guid"]: update(g, r),
+                )
+            else:
+                self.client.mutate(f"create “{name}”", lambda r=resource: create(r))
+
+        for entity in self._managed_entities(entity_type):
+            if entity["name"] not in defined:
+                self.client.mutate(
+                    f"delete orphaned {kind} “{entity['name']}”",
+                    lambda g=entity["guid"]: delete(g),
+                )
+
+    # language=graphql
+    _SEARCH = """
+    query ($query: String!) {
+      actor {
+        entitySearch(query: $query) {
+          results {
+            entities {
+              guid
+              name
+              tags {
+                key
+                values
+              }
+            }
+          }
+        }
+      }
+    }
+    """
+
+    def _managed_entities(self, entity_type: str) -> list[dict]:
+        """All entities of ``entity_type`` in the account tagged as managed by us."""
+        query = (
+            f"type = '{entity_type}' AND accountId = {self.account_id} "
+            f"AND tags.`{self.managed_tag_key}` = '{self.managed_tag_value}'"
+        )
+        data = self.client.call(self._SEARCH, {"query": query})
+        return data["actor"]["entitySearch"]["results"]["entities"]
+
+    def _find_entity(self, name: str, entity_type: str) -> dict | None:
+        """The managed entity of ``entity_type`` named ``name``, or None.
+
+        Raises if a same-named entity exists but is NOT managed by us — we must
+        never clobber a hand-built resource.
+        """
+        query = f"name = '{name}' AND type = '{entity_type}' AND accountId = {self.account_id}"
+        data = self.client.call(self._SEARCH, {"query": query})
+        entities = data["actor"]["entitySearch"]["results"]["entities"]
+        # entitySearch matches substrings; keep only exact-name matches.
+        entities = [e for e in entities if e["name"] == name]
+        if not entities:
+            return None
+        if len(entities) > 1:
+            raise NewRelicUpdaterError(
+                f"Multiple {entity_type} entities named '{name}' found — refusing to "
+                "guess. Resolve the duplicate in New Relic first."
+            )
+        entity = entities[0]
+        tags = {t["key"]: t["values"] for t in entity.get("tags") or []}
+        if self.managed_tag_value not in tags.get(self.managed_tag_key, []):
+            raise NewRelicUpdaterError(
+                f"A {entity_type} named '{name}' exists but is not managed by this tool "
+                f"(missing tag {self.managed_tag_key}={self.managed_tag_value}). Refusing "
+                "to overwrite it. Rename or delete it, or tag it manually to adopt it."
+            )
+        return entity
+
+    # -- Dashboards -----------------------------------------------------------
+
+    def _sync_dashboards(self, dashboards: list[Dashboard]) -> None:
+        """Upsert defined dashboards, then delete managed ones no longer defined."""
+        defined = {d.name: d for d in dashboards}
+        self._reconcile(
+            kind="dashboard",
+            entity_type="DASHBOARD",
+            defined=defined,
+            create=self._create_dashboard,
+            update=self._update_dashboard,
+            delete=self._delete_dashboard,
+        )
+
+    def _dashboard_input(self, dashboard: Dashboard) -> dict:
+        """Serialize a dashboard, injecting our account id into account-less queries."""
+        payload = dashboard.as_nr_dict()
+        for page in payload["pages"]:
+            for widget in page["widgets"]:
+                for nrql in widget["rawConfiguration"].get("nrqlQueries", []):
+                    if not nrql["accountIds"]:
+                        nrql["accountIds"] = [self.account_id]
+        return payload
+
+    # language=graphql
+    _CREATE = """
+    mutation ($accountId: Int!, $dashboard: DashboardInput!) {
+      dashboardCreate(accountId: $accountId, dashboard: $dashboard) {
+        entityResult {
+          guid
+        }
+        errors {
+          description
+          type
+        }
+      }
+    }
+    """
+
+    # language=graphql
+    _TAG = """
+    mutation ($guid: EntityGuid!, $tags: [TaggingTagInput!]!) {
+      taggingAddTagsToEntity(guid: $guid, tags: $tags) {
+        errors {
+          message
+          type
+        }
+      }
+    }
+    """
+
+    def _create_dashboard(self, dashboard: Dashboard) -> None:
+        data = self.client.call(
+            self._CREATE,
+            {"accountId": self.account_id, "dashboard": self._dashboard_input(dashboard)},
+        )
+        result = data["dashboardCreate"]
+        if result["errors"]:
+            raise NewRelicUpdaterError(f"dashboardCreate: {result['errors']}")
+        guid = result["entityResult"]["guid"]
+        # Tag it so future runs recognize it as ours.
+        tag_data = self.client.call(
+            self._TAG,
+            {
+                "guid": guid,
+                "tags": [{"key": self.managed_tag_key, "values": [self.managed_tag_value]}],
+            },
+        )
+        if tag_data["taggingAddTagsToEntity"]["errors"]:
+            raise NewRelicUpdaterError(
+                f"taggingAddTagsToEntity: {tag_data['taggingAddTagsToEntity']['errors']}"
+            )
+
+    # language=graphql
+    _UPDATE = """
+    mutation ($guid: EntityGuid!, $dashboard: DashboardInput!) {
+      dashboardUpdate(guid: $guid, dashboard: $dashboard) {
+        entityResult {
+          guid
+        }
+        errors {
+          description
+          type
+        }
+      }
+    }
+    """
+
+    def _update_dashboard(self, guid: str, dashboard: Dashboard) -> None:
+        data = self.client.call(
+            self._UPDATE, {"guid": guid, "dashboard": self._dashboard_input(dashboard)}
+        )
+        result = data["dashboardUpdate"]
+        if result["errors"]:
+            raise NewRelicUpdaterError(f"dashboardUpdate: {result['errors']}")
+
+    # language=graphql
+    _DELETE = """
+    mutation ($guid: EntityGuid!) {
+      dashboardDelete(guid: $guid) {
+        status
+        errors {
+          description
+          type
+        }
+      }
+    }
+    """
+
+    def _delete_dashboard(self, guid: str) -> None:
+        data = self.client.call(self._DELETE, {"guid": guid})
+        result = data["dashboardDelete"]
+        if result["errors"]:
+            raise NewRelicUpdaterError(f"dashboardDelete: {result['errors']}")

newrelic_as_code-0.1.0/newrelic_as_code/utils.py

@@ -0,0 +1,6 @@
+def echo(message: str, prefix: str = "->> ") -> None:
+    """Print a message with a visible prefix.
+
+    The prefix makes reconcile output easy to spot in CI logs.
+    """
+    print(f"{prefix}{message}", flush=True)  # noqa: T201

newrelic_as_code-0.1.0/pyproject.toml

@@ -0,0 +1,124 @@
+[project]
+name = "newrelic-as-code"
+# Changing the version automatically publishes to PyPI (see DEVELOPMENT.md)
+version = "0.1.0"
+description = "Define New Relic dashboards as code and reconcile them to an account"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Ilia Peterov", email = "ipeterov1@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.0",
+    "requests>=2.26",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Systems Administration",
+]
+
+[project.urls]
+Homepage = "https://github.com/ipeterov/newrelic-as-code"
+Repository = "https://github.com/ipeterov/newrelic-as-code"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "newrelic_as_code/",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["newrelic_as_code"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1",
+    "ruff>=0.15",
+]
+
+[tool.pytest.ini_options]
+addopts = "--tb=short"
+
+[tool.ruff]
+line-length = 100  # Soft target
+
+[tool.ruff.lint]
+unfixable = ["F401"]
+select = [
+    "E",
+    "W",
+    "F",
+    "ERA",
+    "I",
+    "ASYNC",
+    "S",
+    "BLE",
+    "B",
+    "A",
+    "C4",
+    "DTZ",
+    "T10",
+    "EXE",
+    "ISC",
+    "INP",
+    "PIE",
+    "T20",
+    "LOG",
+    "G",
+    "RSE",
+    "RET",
+    "SLF",
+    "SIM",
+    "SLOT",
+    "TC",
+    "PTH",
+    "C90",
+    "N",
+    "PGH",
+    "PL",
+    "UP",
+    "FURB",
+    "RUF",
+]
+ignore = [
+    "E501",  # don't enforce line length - just try to fit in 100 chars when formatting
+    "G004",  # f-strings are better than clunky logging.basicConfig
+    "PLC0415",  # dynamic imports are ok to avoid circular
+    "PLC0414",  # conflicts with F401 explicit re-export
+    "SIM103",  # I don't like simplifying the last condition with early return pattern
+    "SIM108",  # Ternaries can be less readable - I want to decide myself
+    "N815",  # can't enforce this for external APIs, and I already follow it
+    "S101",  # asserts are totally normal in pytest
+    "PLR0913",  # totally normal in pytest to have lots of args (fixtures)
+    "PLR2004",  # too sensitive to normal magic constants in tests
+    "N818",  # not every exception is an error
+    "C901",
+    "PLR0911",
+    "PLR0912",
+    "PLR0915",
+    "TC001",  # those break libs that rely on type inspection
+    "TC002",
+    "TC003",
+    "UP037",
+]
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+force-wrap-aliases = true
+combine-as-imports = true
+
+[tool.ruff.lint.per-file-ignores]
+# Reconcile tests deliberately reach into private reconcile internals.
+"tests/**" = ["SLF001"]