backstage-catalog-client

A python client for the Backstage catalog API. Only uses native python datatypes.

Usage

To use a ready-made client, import it and make requests

import asyncio
import json
from backstage_catalog_client import HttpxClient


async def main():
    with HttpxClient("https://demo.backstage.io/") as backstage:
        data = await backstage.get_entities()
        for entity in data.items[:1]:
            print(json.dumps(entity, indent=2))


if __name__ == "__main__":
    asyncio.run(main())

if you're using the HttpxClient, you can also optionally pass your own fully-configured httpx.AsyncClient and make requests that way

import asyncio
import httpx
import json
from backstage_catalog_client import HttpxClient


async def main():
    client = httpx.AsyncClient(base_url="https://demo.backstage.io", timeout=.5)
    backstage = HttpxClient(client=client)
    data = await backstage.get_entities()
    for entity in data.items[:1]:
        print(json.dumps(entity, indent=2))

    # important!  don't forget to clean up your client
    await client.aclose()


if __name__ == "__main__":
    asyncio.run(main())

Building your own client

This package exports both an AsyncCatalogApi and a SyncCatalogApi as python protocols. You can use these to implement your own clients for the Catalog API.

For example, if you'd like to implement your own synchronous Catalog API client:

from typing import List
from backstage_catalog_client.raw_entity import RawEntity
from backstage_catalog_client import SyncCatalogApi
from backstage_catalog_client.models import GetEntitiesResponse

class HighPerformanceCatalogApi(SyncCatalogApi):
    """
    A high-performance client that never makes a network request.
    Stable, speedy, and (relatively) useless
    """
    def getEntities(self, request=None, options=None) -> GetEntitiesResponse:
        items: List[RawEntity] = [
            {
                "apiVersion": "backstage.io/v1alpha1",
                "kind": "Component",
                "metadata": {
                    "name": "wayback-search",
                    "namespace": "default"
                },
                "spec": {
                    "type": "service",
                    "owner": "team-a",
                    "lifecycle": "experimental"
                }
            }
        ]
        return GetEntitiesResponse(items=items)
    # ... other methods ...


def main():
    client: SyncCatalogApi = HighPerformanceCatalogApi()
    data = client.get_entities()
    for item in data.items:
        print(item)

if __name__ == "__main__":
    main()