ISSUE-1836: Add Dashboard Support

[jpavlav]

Addresses ISSUE-1836
#1836
The impetus for these changes is a project I'm working on at work. We want to create a dynamically updating dashboard that helps prioritize maintenance operations. I realize this is a large PR, and one large commit, but I feel like the work in it's entirety makes sense when looked at together. Additionally, there are some changes that were just formatting, in the case where spacing or anything along those lines have changed, that was auto-formatting and accepted by the linting tox -e lint.

jira/client.py

• Imported DashboardItemProperty, DashboardItemPropertyKey, and Gadget resources to client for use in new methods.
• Updated the dashboards method to include the gadgets that exist on a given dashboard. This is a logical association that makes sense, but isn't directly exposed in the API.
• Added create_dashboard method. It creates a dashboard via the API and returns a Dashbord object.
• Added copy_dashboard method.
• Added update_dashboard_automatic_refresh_seconds method. This calls the internal API, which is why it's decorated with experimental and cloud. This might change in the future, but it really is a handy thing to have, otherwise, the user has to configure this in the web interface.

---

• Added dashboard_item_property method. This is available on both cloud and server.
• Added dashboard_item_property_keys method. This is available on both cloud and server.
• Added set_dashboard_item_property method. This is available on both cloud and server.

---

^^ These methods all provide a means of adding arbitrary metadata to dashboard_items (gadgets) and/or configure them via specific keys.

• Added dashboard_gadgets method. This returns the gadgets associated with a given dashboard. It also iterates over the keys for this gadget's properties, generating a list of DashboardItemProperty objects that are associated with each gadget. This makes it really easy for the user to associate which configuration/metadata goes with which gadget.
• Added gadgets method. This returns a list of from jira of all the gadgets that are available to add to any dashboard.
• Added add_gadget_to_dashboard method. This allows the user to add gadgets to a specified dashboard.
• Added the protected method _get_internal_url. This is very similar to get_url or get_latest url, where options are updated to allow for easy resolution of paths that are on the internal jira api.
• Updated the _find_for_resource type hint on ids because it is possible that a resource requires more than 2 ids to resolve it's url.

jira/resources.py

• Added the new resources DashboardItemProperty, DashboardItemPropertyKey, and Gadget to the __all__ list so they are represented.
• Updated the typehint on the find method for the same reason as the _find_for_resource method.
• Added a gadgets attribute to the Dashboard resource to house gadget references.
• Added DashbordItemPropertyKey resource.
• Added DashboardItemProperty resource. The update and delete methods are overridden here because it does not have a self attribute. This is kind of in an in between space as far as being considered a resource, but for ease of use as an interface, it makes sense for it to be considered.
• Added Gadget resource. It too has overridden update and delete methods for the aforementioned reasons.

jira/utils/init.py

• Added cloud convenience decorator for client methods that make calls that are only available on the cloud api. It checks the client instance to see if it _is_cloud. If not, it logs a warning and returns None. This was the convention seen on other endpoints on the client.
• Added experimental convenience decorator for client methods that make calls that are experimental. It attempts to run the client method, if a JIRAError is raised that has a response object, the response is checked for a status code in [404, 405] indicating either the path no longer accepts the HTTP verb or no longer exists, and then logs a warning and returns None. Otherwise it reraises the error

^^ Regarding these convenience decorators, it makes it really apparent to developers which calls are for the cloud and/or experimental.

• Added remove_empty_attributes convenience method. I found myself having to remove empty attributes or add a lot of branching in order to accommodate optional payload parameters or path parameters. This function made that easier.

Finally I wrote tests to cover these changes. These tests worked for me locally against my docker jira server instance. However, most of them didn't run, because the test checks the environment to find out where it is running.

For the cloud tests, I signed up for a trial account for jira cloud and ran them against my instance. They all panned out okay and cleaned up after themselves appropriately.

[adehad]

An excellent quality PR, still a few things that I think should be addressed before merging, but a promising start!

[jpavlav]

Thanks for taking a look! I'll make another commit with some updates addressing your feedback.

[adehad]

Nice, there is one pending thing we need to look at here.

And that is the resource_class_map in the resources.py file:

jira/jira/resources.py

Line 1647 in c51c8a3

r"dashboard/[^/]+$": Dashboard,

What we are looking at is a regex mapping of the URLs to the resource types.
From what I can see from the REST API reference we are dealing with:
https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-dashboards/#api-rest-api-2-dashboard-get

# DashboardItemProperty
/rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties
# Example regex pattern for the map:
# https://regex101.com/r/1Nw7U6/1
# r"dashboard/[^/]+/items/[^/]+/properties$"

# DashboardItemKey
/rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}

# DashboardGadget
/rest/api/2/dashboard/{dashboardId}/gadget/{gadgetId}

Once this is in we can add to your existing tests an isinstance() check on the class type

[jpavlav]

@adehad I think I've got it now. I added the paths to the new resources. Added some more data points for the parameterized test_generic_resource that cover the new additions to that resource map dict. I also peppered the dashboard tests themselves with isinstance assertions where I thought it made sense. The cloud tests are still passing locally for me so figured 👍 . Let me know if there is anything else I need to address please 😄

[adehad]

excellent. I'll need to wait till later to actually run the cloud tests to merge (@studioj if you are able to confirm feel free to squash merge)