Feature: specify grafana organisation for client

[lilatomic]

Description

Adds awareness of Grafana Orgs. This allows requests to be made against a specific org instead of the "current" org of the user.
fixes #126

Implemented using the "X-Grafana-Org-Id" header docs.

I didn't find a doc that looked like a place to document this feature. Where do you think it should go? or is the arg list good enough?

Checklist

• The patch has appropriate test coverage
• The patch follows the style guidelines of this project
• The patch has appropriate comments, particularly in hard-to-understand areas
• The documentation was updated corresponding to the patch
• I have performed a self-review of this patch

[codecov]

Codecov Report

Merging #127 (1affa1c) into main (a13389b) will increase coverage by 0.01%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##             main     #127      +/-   ##
==========================================
+ Coverage   94.15%   94.16%   +0.01%     
==========================================
  Files          25       25              
  Lines        1625     1628       +3     
==========================================
+ Hits         1530     1533       +3     
  Misses         95       95              

Files	Coverage Δ
grafana_client/api.py	100.00% <ø> (ø)
grafana_client/client.py	95.83% <100.00%> (+0.13%)	⬆️

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[amotl]

I didn't find a doc that looked like a place to document this feature. Where do you think it should go? or is the arg list good enough?

Effectively, there is only the main README, so it should go between "Authentication" and "Timeout settings", with a headline like "Configure Organization".

Let's directly refer to https://grafana.com/docs/grafana/latest/developers/http_api/auth/#x-grafana-org-id-header over there, and cite the resource like

When using the organization_id parameter to GrafanaClient, its value will be populated into the X-Grafana-Org-Id HTTP request header.

[It] is an optional property that specifies the organization to which the action is applied. If it is not set, the created key belongs to the current context org. Use this header in all requests except those regarding admin.

[amotl]

Thank you very much. Can I ask you to add a little section about the feature to the README file?

[lilatomic]

I've tested this manually a bit and wrote up the following test (we can add it when we get integration tests):

docker run --rm -p 3000:3000 grafana/grafana:10.1.5

def mk_gfn(organization_id):
    return GrafanaApi(("admin", "admin",), "localhost", 3000, organization_id=organization_id)


def mk_org(g: GrafanaApi) -> int:
    return g.organization.create_organization({"name": str(random.randint(0, 10000))})["orgId"]


def test_org_multiple_with_header():
    """Test that multiple instances of GrafanaApi will interact with the correct Org"""
    # Create a GrafanaApi with no org and create a new org
    g = mk_gfn(None)
    org1_id = mk_org(g)
    org2_id = mk_org(g)

    # Create GrafanaApis in both orgs
    g1 = mk_gfn(org1_id)
    g2 = mk_gfn(org2_id)

    # Create resources in org1 and check that only org1 can see them
    g1.dashboard.update_dashboard({"dashboard": {"title": "d1"}})
    r1 = g1.search.search_dashboards(type_="dash-db")
    print("dashboards in org1", r1)
    assert len(r1) == 1
    r2 = g2.search.search_dashboards(type_="dash-db")
    print("dashboards in org2", r2)
    assert len(r2) == 0


def test_org_header_ignores_context():
    """Test that a GrafanaApi bound to an Org is not affected by changing the current Org context"""
    g = mk_gfn(None)
    org1_id = mk_org(g)

    # Create resources in org1
    g1 = mk_gfn(org1_id)
    g1.dashboard.update_dashboard({"dashboard": {"title": "d1"}})
    r1 = g1.search.search_dashboards(type_="dash-db")
    print("dashboards in org1", r1)
    assert len(r1) == 1

    # switch current context to main org
    g.user.switch_actual_user_organisation(1)

    # verify org1 GrafanaApi is still bound to org1
    r1 = g1.search.search_dashboards(type_="dash-db")
    print("dashboards in org1", r1)
    assert len(r1) == 1

[lilatomic]

Thanks for outlining the documentation you'd like to see. I've done the writeup, if you're happy with it we should be good to merge!

[amotl]

Thank you very much.

[lilatomic]

You're welcome! It was a pleasure working with you, and I want to thank you for your continued maintenance of this library!

[amotl]

Dito. Do you already know about grafana-client's sister package, grafana-wtf? If that resonates with you, and you will come up with ideas for features yet missing, we will be all ears.