From b17b17aa77eb0f5b8494373e5eac7a96dbe95522 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Fri, 6 Jun 2025 17:53:32 +0200 Subject: [PATCH] Added high-level diagrams --- ...tlassian Platform & Marketplace Clients.md | 234 ++++++++++++++++++ .codeboarding/Bamboo API Client.md | 46 ++++ .codeboarding/Bitbucket API Client.md | 181 ++++++++++++++ .codeboarding/Confluence API Client.md | 60 +++++ .codeboarding/Jira Ecosystem Clients.md | 124 ++++++++++ .codeboarding/REST Client Core.md | 83 +++++++ .codeboarding/Utility & Error Handling.md | 135 ++++++++++ .codeboarding/on_boarding.md | 162 ++++++++++++ 8 files changed, 1025 insertions(+) create mode 100644 .codeboarding/Atlassian Platform & Marketplace Clients.md create mode 100644 .codeboarding/Bamboo API Client.md create mode 100644 .codeboarding/Bitbucket API Client.md create mode 100644 .codeboarding/Confluence API Client.md create mode 100644 .codeboarding/Jira Ecosystem Clients.md create mode 100644 .codeboarding/REST Client Core.md create mode 100644 .codeboarding/Utility & Error Handling.md create mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/Atlassian Platform & Marketplace Clients.md b/.codeboarding/Atlassian Platform & Marketplace Clients.md new file mode 100644 index 000000000..909b2065a --- /dev/null +++ b/.codeboarding/Atlassian Platform & Marketplace Clients.md @@ -0,0 +1,234 @@ +```mermaid +graph LR + AtlassianRestAPI["AtlassianRestAPI"] + Crowd_API_Client["Crowd API Client"] + StatusPage_API_Client["StatusPage API Client"] + MarketPlace_API_Client["MarketPlace API Client"] + Cloud_Admin_Organizations_API_Client["Cloud Admin Organizations API Client"] + Cloud_Admin_Users_API_Client["Cloud Admin Users API Client"] + Crowd_API_Client -- "inherits from and uses" --> AtlassianRestAPI + StatusPage_API_Client -- "inherits from and uses" --> AtlassianRestAPI + MarketPlace_API_Client -- "inherits from and uses" --> AtlassianRestAPI + Cloud_Admin_Organizations_API_Client -- "inherits from and uses" --> AtlassianRestAPI + Cloud_Admin_Users_API_Client -- "inherits from and uses" --> AtlassianRestAPI +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the structure and interactions within the Atlassian Platform & Marketplace Clients subsystem. The core component, `AtlassianRestAPI`, provides the fundamental HTTP communication and authentication mechanisms. All other client components, including `Crowd API Client`, `StatusPage API Client`, `MarketPlace API Client`, `Cloud Admin Organizations API Client`, and `Cloud Admin Users API Client`, inherit from and utilize the `AtlassianRestAPI` to interact with their respective Atlassian services. This design promotes reusability of network and authentication logic, allowing each client to focus on the specific API endpoints and data models of its domain (Crowd for user/group management, StatusPage for public status updates, Marketplace for application information, and Cloud Admin for organization and user profile management). + +### AtlassianRestAPI +This is the foundational component for all Atlassian API interactions. It manages HTTP sessions, various authentication methods (basic, token, OAuth1, OAuth2, Kerberos, header), SSL verification, proxy settings, and implements robust retry mechanisms for handling transient network or API rate limit issues. It provides a standardized interface for performing GET, POST, PUT, PATCH, and DELETE operations against Atlassian services. + + +**Related Classes/Methods**: + +- `atlassian.rest_client.AtlassianRestAPI` (43:1001) +- `atlassian.rest_client.AtlassianRestAPI.__init__` (72:202) +- `atlassian.rest_client.AtlassianRestAPI.__exit__` (207:208) +- `atlassian.rest_client.AtlassianRestAPI._create_basic_session` (210:211) +- `atlassian.rest_client.AtlassianRestAPI._create_token_session` (213:214) +- `atlassian.rest_client.AtlassianRestAPI._create_oauth_session` (224:232) +- `atlassian.rest_client.AtlassianRestAPI._create_oauth2_session` (234:245) +- `atlassian.rest_client.AtlassianRestAPI._create_kerberos_session` (219:222) +- `atlassian.rest_client.AtlassianRestAPI._create_header_session` (216:217) +- `atlassian.rest_client.AtlassianRestAPI._update_header` (247:254) +- `atlassian.rest_client.AtlassianRestAPI._response_handler` (257:265) +- `atlassian.rest_client.AtlassianRestAPI._calculate_backoff_value` (267:286) +- `atlassian.rest_client.AtlassianRestAPI._retry_handler` (288:318) +- `atlassian.rest_client.AtlassianRestAPI.log_curl_debug` (320:344) +- `atlassian.rest_client.AtlassianRestAPI.resource_url` (346:353) +- `atlassian.rest_client.AtlassianRestAPI.url_joiner` (356:360) +- `atlassian.rest_client.AtlassianRestAPI.close` (362:363) +- `atlassian.rest_client.AtlassianRestAPI.request` (365:446) +- `atlassian.rest_client.AtlassianRestAPI.get` (450:463) +- `atlassian.rest_client.AtlassianRestAPI._get_response_content` (580:606) +- `atlassian.rest_client.AtlassianRestAPI.post` (610:623) +- `atlassian.rest_client.AtlassianRestAPI.put` (731:743) +- `atlassian.rest_client.AtlassianRestAPI.patch` (832:867) +- `atlassian.rest_client.AtlassianRestAPI.delete` (871:882) +- `atlassian.rest_client.AtlassianRestAPI.raise_for_status` (964:996) +- `atlassian.rest_client.AtlassianRestAPI.session` (999:1001) + + +### Crowd API Client +This component provides a high-level interface for interacting with the Atlassian Crowd API. It encapsulates functionalities for managing users (e.g., creation, activation, deactivation, deletion, retrieving user details and group memberships) and groups (e.g., adding users to groups, creating new groups, retrieving group members). Additionally, it offers methods for checking plugin health and managing plugin licenses within Crowd. + + +**Related Classes/Methods**: + +- `atlassian.crowd.Crowd` (12:297) +- `atlassian.crowd.Crowd.__init__` (17:26) +- `atlassian.crowd.Crowd._crowd_api_url` (28:29) +- `atlassian.crowd.Crowd._user_change_status` (31:56) +- `atlassian.crowd.Crowd.user` (58:65) +- `atlassian.crowd.Crowd.user_activate` (67:73) +- `atlassian.crowd.Crowd.user_create` (75:108) +- `atlassian.crowd.Crowd.user_deactivate` (110:117) +- `atlassian.crowd.Crowd.user_delete` (119:128) +- `atlassian.crowd.Crowd.user_groups` (130:139) +- `atlassian.crowd.Crowd.group_members` (141:152) +- `atlassian.crowd.Crowd.is_user_in_group` (154:165) +- `atlassian.crowd.Crowd.group_add_user` (167:181) +- `atlassian.crowd.Crowd.health_check` (183:194) +- `atlassian.crowd.Crowd.get_plugins_info` (196:202) +- `atlassian.crowd.Crowd.get_plugin_info` (204:210) +- `atlassian.crowd.Crowd.get_plugin_license_info` (212:218) +- `atlassian.crowd.Crowd.upload_plugin` (220:234) +- `atlassian.crowd.Crowd.delete_plugin` (236:243) +- `atlassian.crowd.Crowd.check_plugin_manager_status` (245:247) +- `atlassian.crowd.Crowd.update_plugin_license` (249:262) +- `atlassian.crowd.Crowd.memberships` (265:280) +- `atlassian.crowd.Crowd.group_create` (282:297) + + +### StatusPage API Client +This component provides a comprehensive set of methods for interacting with the Atlassian Statuspage API. It enables management of pages, organizations, users, embed configurations, subscribers, incidents, postmortems, components, component groups, and metrics, offering functionalities like listing, creating, updating, and deleting these entities. + + +**Related Classes/Methods**: + +- `atlassian.statuspage.StatusPage` (108:3133) +- `atlassian.statuspage.StatusPage.__init__` (111:112) +- `atlassian.statuspage.StatusPage.page_list_pages` (114:133) +- `atlassian.statuspage.StatusPage.get_page` (135:158) +- `atlassian.statuspage.StatusPage.page_update` (160:190) +- `atlassian.statuspage.StatusPage.organization_get_users` (192:218) +- `atlassian.statuspage.StatusPage.organization_get_user_permissions` (220:245) +- `atlassian.statuspage.StatusPage.organization_set_user_permissions` (247:291) +- `atlassian.statuspage.StatusPage.page_get_embed_config_settings` (293:316) +- `atlassian.statuspage.StatusPage.page_update_embed_config_settings` (318:356) +- `atlassian.statuspage.StatusPage.page_access_users_list` (358:387) +- `atlassian.statuspage.StatusPage.page_get_access_user` (389:414) +- `atlassian.statuspage.StatusPage.page_set_access_user` (416:453) +- `atlassian.statuspage.StatusPage.page_delete_access_user` (455:481) +- `atlassian.statuspage.StatusPage.page_get_components_access_user` (483:513) +- `atlassian.statuspage.StatusPage.page_add_components_access_user` (515:543) +- `atlassian.statuspage.StatusPage.page_replace_components_access_user` (545:573) +- `atlassian.statuspage.StatusPage.page_delete_components_access_user` (575:603) +- `atlassian.statuspage.StatusPage.page_delete_component_access_user` (605:633) +- `atlassian.statuspage.StatusPage.page_get_metrics_access_user` (635:661) +- `atlassian.statuspage.StatusPage.page_add_metrics_access_user` (663:691) +- `atlassian.statuspage.StatusPage.page_replace_metrics_access_user` (693:721) +- `atlassian.statuspage.StatusPage.page_delete_metrics_access_user` (723:751) +- `atlassian.statuspage.StatusPage.page_delete_metric_access_user` (753:781) +- `atlassian.statuspage.StatusPage.page_get_access_groups` (783:810) +- `atlassian.statuspage.StatusPage.page_get_access_group` (812:837) +- `atlassian.statuspage.StatusPage.page_create_access_group` (839:882) +- `atlassian.statuspage.StatusPage.page_replace_access_group` (884:929) +- `atlassian.statuspage.StatusPage.page_delete_access_group` (931:957) +- `atlassian.statuspage.StatusPage.page_add_components_to_access_group` (959:986) +- `atlassian.statuspage.StatusPage.page_replace_components_for_access_page` (988:1016) +- `atlassian.statuspage.StatusPage.page_delete_components_for_access_page` (1018:1046) +- `atlassian.statuspage.StatusPage.page_delete_component_for_access_page` (1048:1076) +- `atlassian.statuspage.StatusPage.page_get_components_for_access_group` (1078:1108) +- `atlassian.statuspage.StatusPage.page_get_subscriber` (1110:1135) +- `atlassian.statuspage.StatusPage.page_get_subscribers` (1137:1200) +- `atlassian.statuspage.StatusPage.page_update_subscriber` (1202:1232) +- `atlassian.statuspage.StatusPage.page_unsubscribe_subscriber` (1234:1261) +- `atlassian.statuspage.StatusPage.page_resend_confirmation_subscribers` (1263:1289) +- `atlassian.statuspage.StatusPage.page_create_subscriber` (1291:1317) +- `atlassian.statuspage.StatusPage.page_get_list_unsubscribed` (1319:1346) +- `atlassian.statuspage.StatusPage.page_count_subscribers_by_type` (1348:1376) +- `atlassian.statuspage.StatusPage.page_get_histogram_of_subscribers_with_state` (1378:1401) +- `atlassian.statuspage.StatusPage.page_reactivate_subscribers` (1403:1430) +- `atlassian.statuspage.StatusPage.page_unsubscribe_subscribers` (1432:1471) +- `atlassian.statuspage.StatusPage.page_resend_confirmations_to_subscribers` (1473:1500) +- `atlassian.statuspage.StatusPage.page_create_template` (1502:1528) +- `atlassian.statuspage.StatusPage.page_get_templates` (1530:1560) +- `atlassian.statuspage.StatusPage.page_create_incident` (1562:1587) +- `atlassian.statuspage.StatusPage.page_list_incidents` (1589:1622) +- `atlassian.statuspage.StatusPage.page_list_active_maintenances` (1624:1654) +- `atlassian.statuspage.StatusPage.page_list_upcoming_incidents` (1656:1686) +- `atlassian.statuspage.StatusPage.page_list_scheduled_incidents` (1688:1718) +- `atlassian.statuspage.StatusPage.page_list_unresolved_incidents` (1720:1750) +- `atlassian.statuspage.StatusPage.page_delete_incident` (1752:1773) +- `atlassian.statuspage.StatusPage.page_update_incident` (1775:1802) +- `atlassian.statuspage.StatusPage.page_get_incident` (1804:1829) +- `atlassian.statuspage.StatusPage.page_update_incident_updates` (1831:1861) +- `atlassian.statuspage.StatusPage.page_create_incident_subscriber` (1863:1890) +- `atlassian.statuspage.StatusPage.page_list_incident_subscribers` (1892:1921) +- `atlassian.statuspage.StatusPage.page_unsubscribe_incident_subscriber` (1923:1946) +- `atlassian.statuspage.StatusPage.page_get_incident_subscriber` (1948:1976) +- `atlassian.statuspage.StatusPage.page_resend_confirmation_incident_subscriber` (1978:2005) +- `atlassian.statuspage.StatusPage.page_get_postmortem` (2007:2032) +- `atlassian.statuspage.StatusPage.page_create_postmortem` (2034:2061) +- `atlassian.statuspage.StatusPage.page_delete_postmortem` (2063:2088) +- `atlassian.statuspage.StatusPage.page_publish_postmortem` (2090:2119) +- `atlassian.statuspage.StatusPage.page_revert_postmortem` (2121:2147) +- `atlassian.statuspage.StatusPage.page_create_component` (2149:2176) +- `atlassian.statuspage.StatusPage.page_get_components` (2178:2205) +- `atlassian.statuspage.StatusPage.page_update_component` (2207:2240) +- `atlassian.statuspage.StatusPage.page_delete_component` (2242:2267) +- `atlassian.statuspage.StatusPage.page_get_component` (2269:2294) +- `atlassian.statuspage.StatusPage.page_get_uptime_component` (2296:2341) +- `atlassian.statuspage.StatusPage.page_remove_access_users_from_component` (2343:2369) +- `atlassian.statuspage.StatusPage.page_add_access_users_to_component` (2371:2399) +- `atlassian.statuspage.StatusPage.page_remove_access_users_from_group` (2401:2427) +- `atlassian.statuspage.StatusPage.page_add_access_users_to_group` (2429:2457) +- `atlassian.statuspage.StatusPage.page_create_component_group` (2459:2487) +- `atlassian.statuspage.StatusPage.page_get_list_of_component_groups` (2489:2516) +- `atlassian.statuspage.StatusPage.page_update_component_group` (2518:2548) +- `atlassian.statuspage.StatusPage.page_delete_component_group` (2550:2575) +- `atlassian.statuspage.StatusPage.page_get_component_group` (2577:2602) +- `atlassian.statuspage.StatusPage.page_get_uptime_for_component_group` (2604:2650) +- `atlassian.statuspage.StatusPage.page_add_data_points_to_metric` (2652:2679) +- `atlassian.statuspage.StatusPage.page_get_list_of_metrics` (2681:2708) +- `atlassian.statuspage.StatusPage.page_update_metric` (2710:2741) +- `atlassian.statuspage.StatusPage.page_update_metric_data` (2743:2774) +- `atlassian.statuspage.StatusPage.page_delete_metric` (2776:2801) +- `atlassian.statuspage.StatusPage.page_get_metric` (2803:2828) +- `atlassian.statuspage.StatusPage.page_reset_data_for_metric` (2830:2855) +- `atlassian.statuspage.StatusPage.page_add_data_to_metric` (2857:2886) +- `atlassian.statuspage.StatusPage.page_list_metric_for_metric_provider` (2888:2918) +- `atlassian.statuspage.StatusPage.page_create_metric_for_metric_provider` (2920:2974) +- `atlassian.statuspage.StatusPage.page_list_metric_providers` (2976:2998) +- `atlassian.statuspage.StatusPage.page_create_metric_provider` (3000:3045) +- `atlassian.statuspage.StatusPage.page_get_metric_provider` (3047:3072) +- `atlassian.statuspage.StatusPage.page_update_metric_provider` (3074:3110) +- `atlassian.statuspage.StatusPage.page_delete_metric_provider` (3112:3133) + + +### MarketPlace API Client +This component provides an interface to access information from the Atlassian Marketplace. It allows users to retrieve details about plugins, vendors, applications, specific app versions, and user reviews for applications listed on the Marketplace. + + +**Related Classes/Methods**: + +- `atlassian.marketplace.MarketPlace` (9:84) +- `atlassian.marketplace.MarketPlace.get_plugins_info` (12:25) +- `atlassian.marketplace.MarketPlace.get_vendors_info` (27:40) +- `atlassian.marketplace.MarketPlace.get_application_info` (42:55) +- `atlassian.marketplace.MarketPlace.get_app_versions` (57:69) +- `atlassian.marketplace.MarketPlace.get_app_reviews` (71:84) + + +### Cloud Admin Organizations API Client +This component facilitates interaction with the Atlassian Cloud Admin API for managing organizations. It enables retrieval of organization-specific details, listing of managed accounts within an organization, and searching for users based on various criteria. + + +**Related Classes/Methods**: + +- `atlassian.cloud_admin.CloudAdminOrgs` (11:105) +- `atlassian.cloud_admin.CloudAdminOrgs.__init__` (12:16) +- `atlassian.cloud_admin.CloudAdminOrgs.get_organizations` (18:24) +- `atlassian.cloud_admin.CloudAdminOrgs.get_organization` (26:33) +- `atlassian.cloud_admin.CloudAdminOrgs.get_managed_accounts_in_organization` (35:46) +- `atlassian.cloud_admin.CloudAdminOrgs.search_users_in_organization` (48:105) + + +### Cloud Admin Users API Client +This component provides a focused interface for interacting with the Atlassian Cloud Admin API specifically for user management. Its primary responsibility is to retrieve user profile information for managed accounts within Atlassian Cloud. + + +**Related Classes/Methods**: + +- `atlassian.cloud_admin.CloudAdminUsers` (108:117) +- `atlassian.cloud_admin.CloudAdminUsers.__init__` (109:113) +- `atlassian.cloud_admin.CloudAdminUsers.get_profile` (115:117) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Bamboo API Client.md b/.codeboarding/Bamboo API Client.md new file mode 100644 index 000000000..926883ce7 --- /dev/null +++ b/.codeboarding/Bamboo API Client.md @@ -0,0 +1,46 @@ +```mermaid +graph LR + Bamboo_API_Client["Bamboo API Client"] + REST_Client_Core["REST Client Core"] + Bamboo_Internal_Helpers["Bamboo Internal Helpers"] + Bamboo_API_Client -- "invokes" --> REST_Client_Core + Bamboo_API_Client -- "utilizes" --> Bamboo_Internal_Helpers + Bamboo_Internal_Helpers -- "invokes" --> REST_Client_Core +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the Bamboo API Client, which facilitates interaction with the Bamboo CI/CD API. The core functionality revolves around the `Bamboo API Client` component, which leverages the `REST Client Core` for all HTTP communications. The `Bamboo Internal Helpers` component provides utility functions to assist the `Bamboo API Client` in processing API responses, particularly for pagination and list handling. The overall purpose is to provide a comprehensive and easy-to-use Python interface for managing various aspects of Bamboo, including projects, build plans, branches, build results, deployments, users, groups, permissions, agents, and reports. + +### Bamboo API Client +This component provides a high-level interface for interacting with the Atlassian Bamboo REST API. It includes methods for managing projects, plans, builds, deployments, users, groups, agents, and plugins, abstracting the underlying HTTP communication. + + +**Related Classes/Methods**: + +- `atlassian.bamboo.Bamboo` (11:1472) + + +### REST Client Core +This core component handles the fundamental HTTP communication with Atlassian REST APIs. It provides generic methods for GET, POST, PUT, DELETE requests and utility for constructing resource URLs, serving as the backbone for various Atlassian product clients. + + +**Related Classes/Methods**: + +- `atlassian.rest_client.AtlassianRestAPI` (43:1001) + + +### Bamboo Internal Helpers +This component comprises internal utility methods within the Bamboo API Client, primarily responsible for handling common patterns like pagination and list retrieval from the Bamboo REST API. + + +**Related Classes/Methods**: + +- `atlassian.bamboo.Bamboo.base_list_call` (65:97) +- `atlassian.bamboo.Bamboo._get_generator` (14:63) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Bitbucket API Client.md b/.codeboarding/Bitbucket API Client.md new file mode 100644 index 000000000..cfcda7f84 --- /dev/null +++ b/.codeboarding/Bitbucket API Client.md @@ -0,0 +1,181 @@ +```mermaid +graph LR + BitbucketUnifiedClient["BitbucketUnifiedClient"] + BitbucketBaseComponent["BitbucketBaseComponent"] + BitbucketCloudBaseComponent["BitbucketCloudBaseComponent"] + AtlassianRESTAPIClient["AtlassianRESTAPIClient"] + BitbucketServerGlobalPermissionsManager["BitbucketServerGlobalPermissionsManager"] + BitbucketServerProjectManagement["BitbucketServerProjectManagement"] + BitbucketServerCommonPermissionsManager["BitbucketServerCommonPermissionsManager"] + BitbucketCloudWorkspaceManagement["BitbucketCloudWorkspaceManagement"] + BitbucketCloudProjectManagement["BitbucketCloudProjectManagement"] + BitbucketCloudPermissionManagement["BitbucketCloudPermissionManagement"] + BitbucketCloudMemberManagement["BitbucketCloudMemberManagement"] + BitbucketCloudCommonDataModels["BitbucketCloudCommonDataModels"] + BitbucketUnifiedClient -- "inherits from" --> BitbucketBaseComponent + BitbucketCloudBaseComponent -- "inherits from" --> BitbucketBaseComponent + BitbucketUnifiedClient -- "uses" --> BitbucketCloudBaseComponent + BitbucketServerGlobalPermissionsManager -- "inherits from" --> BitbucketBaseComponent + BitbucketServerProjectManagement -- "inherits from" --> BitbucketBaseComponent + BitbucketServerCommonPermissionsManager -- "inherits from" --> BitbucketBaseComponent + BitbucketCloudWorkspaceManagement -- "inherits from" --> BitbucketCloudBaseComponent + BitbucketCloudProjectManagement -- "inherits from" --> BitbucketCloudBaseComponent + BitbucketCloudPermissionManagement -- "inherits from" --> BitbucketCloudBaseComponent + BitbucketCloudMemberManagement -- "inherits from" --> BitbucketCloudBaseComponent + BitbucketCloudCommonDataModels -- "inherits from" --> BitbucketCloudBaseComponent + BitbucketBaseComponent -- "uses" --> AtlassianRESTAPIClient + BitbucketUnifiedClient -- "uses" --> AtlassianRESTAPIClient + BitbucketUnifiedClient -- "manages" --> BitbucketServerGlobalPermissionsManager + BitbucketUnifiedClient -- "manages" --> BitbucketServerProjectManagement + BitbucketUnifiedClient -- "uses" --> BitbucketCloudWorkspaceManagement + BitbucketCloudBaseComponent -- "uses" --> AtlassianRESTAPIClient + BitbucketServerGlobalPermissionsManager -- "uses" --> AtlassianRESTAPIClient + BitbucketServerProjectManagement -- "uses" --> AtlassianRESTAPIClient + BitbucketServerCommonPermissionsManager -- "uses" --> AtlassianRESTAPIClient + BitbucketCloudWorkspaceManagement -- "uses" --> AtlassianRESTAPIClient + BitbucketCloudWorkspaceManagement -- "manages" --> BitbucketCloudProjectManagement + BitbucketCloudWorkspaceManagement -- "manages" --> BitbucketCloudPermissionManagement + BitbucketCloudWorkspaceManagement -- "manages" --> BitbucketCloudMemberManagement + BitbucketCloudProjectManagement -- "uses" --> AtlassianRESTAPIClient + BitbucketCloudPermissionManagement -- "uses" --> AtlassianRESTAPIClient + BitbucketCloudMemberManagement -- "uses" --> AtlassianRESTAPIClient + BitbucketCloudCommonDataModels -- "uses" --> AtlassianRESTAPIClient +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the Bitbucket API Client subsystem, which provides a unified interface for interacting with both Bitbucket Server and Bitbucket Cloud APIs. It details the core client, base components for common and platform-specific functionalities, and specialized managers for global permissions, project management, workspace management, and common data models, all relying on a low-level REST API client for communication. + +### BitbucketUnifiedClient +Provides a unified interface for interacting with both Bitbucket Server and Bitbucket Cloud APIs, covering functionalities related to projects, repositories, branches, tags, pull requests, webhooks, users, groups, and various administrative and permission management tasks across both Bitbucket platforms. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.Bitbucket` (full file reference) +- `atlassian.bitbucket.server.Server` (full file reference) +- `atlassian.bitbucket.cloud.Cloud` (full file reference) + + +### BitbucketBaseComponent +This foundational component provides common functionalities and attributes shared across different Bitbucket API clients, such as data updating, time format checking, and generic paged data retrieval. It serves as a base class for more specific Bitbucket implementations. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.base.BitbucketBase` (14:204) + + +### BitbucketCloudBaseComponent +This component extends the core Bitbucket base functionalities with features specific to the Bitbucket Cloud environment, such as handling cloud-specific links and paged data structures. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.cloud.base.BitbucketCloudBase` (11:125) + + +### AtlassianRESTAPIClient +A fundamental utility component responsible for executing all HTTP requests (GET, POST, PUT, DELETE) to Atlassian APIs and handling URL construction. It acts as the low-level communication layer for all higher-level API clients. + + +**Related Classes/Methods**: + +- `atlassian.rest_client.AtlassianRestAPI` (43:1001) + + +### BitbucketServerGlobalPermissionsManager +Manages global-level permissions for Bitbucket Server, allowing administrators to define and control access rights for users and groups across the entire Bitbucket instance. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.server.globalPermissions.GlobalPermissions` (6:103) +- `atlassian.bitbucket.server.globalPermissions.Groups` (106:111) +- `atlassian.bitbucket.server.globalPermissions.Users` (114:119) +- `atlassian.bitbucket.server.globalPermissions.PermissionBase` (122:153) +- `atlassian.bitbucket.server.globalPermissions.Group` (156:164) +- `atlassian.bitbucket.server.globalPermissions.User` (167:198) + + +### BitbucketServerProjectManagement +Provides functionalities for managing projects within Bitbucket Server, including operations such as creating, retrieving, updating, and deleting projects, as well as handling project-specific permissions. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.server.projects.Projects` (full file reference) +- `atlassian.bitbucket.server.projects.Project` (full file reference) + + +### BitbucketServerCommonPermissionsManager +Offers a shared set of functionalities for managing permissions in Bitbucket Server, applicable to both projects and repositories, enabling the assignment and revocation of read, write, and administrative access. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.server.common.permissions.Permissions` (6:107) +- `atlassian.bitbucket.server.common.permissions.Groups` (110:115) +- `atlassian.bitbucket.server.common.permissions.Users` (118:123) +- `atlassian.bitbucket.server.common.permissions.PermissionBase` (126:161) +- `atlassian.bitbucket.server.common.permissions.Group` (164:173) +- `atlassian.bitbucket.server.common.permissions.User` (176:220) + + +### BitbucketCloudWorkspaceManagement +Manages workspaces in Bitbucket Cloud, providing methods to list, retrieve, and check the existence of workspaces. It also serves as an entry point for managing projects, members, and permissions associated with a specific workspace. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.cloud.workspaces.Workspaces` (full file reference) +- `atlassian.bitbucket.cloud.workspaces.Workspace` (full file reference) + + +### BitbucketCloudProjectManagement +Focuses on project-related operations within Bitbucket Cloud workspaces, allowing for the creation, retrieval, updating, and deletion of projects. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.cloud.workspaces.projects.Projects` (9:120) +- `atlassian.bitbucket.cloud.workspaces.projects.Project` (123:215) + + +### BitbucketCloudPermissionManagement +Handles the administration of permissions for Bitbucket Cloud workspaces and repositories, enabling the assignment and management of access rights for users and groups. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.cloud.workspaces.permissions.Permissions` (7:52) +- `atlassian.bitbucket.cloud.workspaces.permissions.WorkspaceMembership` (55:97) +- `atlassian.bitbucket.cloud.workspaces.permissions.RepositoryPermission` (100:124) + + +### BitbucketCloudMemberManagement +Manages members within Bitbucket Cloud workspaces, providing functionalities to list and retrieve details of workspace members. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.cloud.workspaces.members.WorkspaceMembers` (6:39) +- `atlassian.bitbucket.cloud.workspaces.members.WorkspaceMember` (42:64) + + +### BitbucketCloudCommonDataModels +Defines the data structures for common entities in Bitbucket Cloud, such as users, participants in pull requests, build statuses, and comments, facilitating consistent data representation across the API. + + +**Related Classes/Methods**: + +- `atlassian.bitbucket.cloud.common.users.User` (4:31) +- `atlassian.bitbucket.cloud.common.users.Participant` (34:79) +- `atlassian.bitbucket.cloud.common.builds.Build` (4:86) +- `atlassian.bitbucket.cloud.common.comments.Comment` (5:50) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Confluence API Client.md b/.codeboarding/Confluence API Client.md new file mode 100644 index 000000000..41243f741 --- /dev/null +++ b/.codeboarding/Confluence API Client.md @@ -0,0 +1,60 @@ +```mermaid +graph LR + Confluence_API_Client["Confluence API Client"] + REST_API_Handler["REST API Handler"] + API_Error_Definitions["API Error Definitions"] + General_Utilities["General Utilities"] + Confluence_API_Client -- "uses" --> REST_API_Handler + Confluence_API_Client -- "raises/handles" --> API_Error_Definitions + Confluence_API_Client -- "uses" --> General_Utilities + REST_API_Handler -- "raises/handles" --> API_Error_Definitions +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components of the Confluence API Client subsystem within the `atlassian-python-api` library. The `Confluence API Client` acts as the primary interface for Confluence-specific operations, relying on the `REST API Handler` for all underlying HTTP communication. Error handling across the subsystem is centralized through `API Error Definitions`, which are utilized by both the `Confluence API Client` and the `REST API Handler`. Additionally, the `Confluence API Client` leverages `General Utilities` for data formatting and normalization tasks before interacting with the Confluence API. + +### Confluence API Client +Facilitates interaction with the Confluence API, allowing operations on pages, spaces, comments, attachments, labels, content history, templates, and user/group permissions within Confluence. + + +**Related Classes/Methods**: + +- `atlassian.confluence.Confluence` (full file reference) + + +### REST API Handler +This component is responsible for the core HTTP communication with Atlassian REST APIs. It manages the underlying network requests, handles different authentication mechanisms (basic, token, OAuth), applies request parameters and headers, and implements robust features like SSL verification, timeouts, and exponential backoff with retries for resilient API interactions. + + +**Related Classes/Methods**: + +- `atlassian.rest_client.AtlassianRestAPI` (43:1001) + + +### API Error Definitions +This component defines a set of custom exception classes that provide specific error types for various API-related failures. These exceptions allow for more precise error handling and differentiation of issues such as resource not found, permission denied, invalid input, or conflicts during API operations. + + +**Related Classes/Methods**: + +- `atlassian.errors.ApiError` (4:7) +- `atlassian.errors.ApiNotFoundError` (10:11) +- `atlassian.errors.ApiPermissionError` (14:15) +- `atlassian.errors.ApiValueError` (18:19) +- `atlassian.errors.ApiConflictError` (22:23) + + +### General Utilities +This component offers a collection of general-purpose helper functions that support various aspects of the `atlassian-python-api` library. These utilities include functions for HTML content formatting (e.g., for Confluence page bodies) and character normalization, which are used to process or prepare data before sending it to or after receiving it from the Atlassian APIs. + + +**Related Classes/Methods**: + +- `atlassian.utils.symbol_normalizer` (260:307) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Jira Ecosystem Clients.md b/.codeboarding/Jira Ecosystem Clients.md new file mode 100644 index 000000000..b3093329f --- /dev/null +++ b/.codeboarding/Jira Ecosystem Clients.md @@ -0,0 +1,124 @@ +```mermaid +graph LR + Jira_Ecosystem_Clients["Jira Ecosystem Clients"] + REST_Client_Core["REST Client Core"] + Jira_Service_Desk_API_Client["Jira Service Desk API Client"] + Jira_Core_Software_API_Client["Jira Core/Software API Client"] + Jira_Assets_Cloud_API_Client["Jira Assets Cloud API Client"] + Jira_Portfolio_API_Client["Jira Portfolio API Client"] + Jira_Insight_Server_DC_API_Client["Jira Insight Server/DC API Client"] + Jira_Xray_API_Client["Jira Xray API Client"] + API_Error_Handling["API Error Handling"] + Jira_Service_Desk_API_Client -- "inherits from" --> REST_Client_Core + Jira_Core_Software_API_Client -- "inherits from" --> REST_Client_Core + Jira_Assets_Cloud_API_Client -- "inherits from" --> REST_Client_Core + Jira_Portfolio_API_Client -- "inherits from" --> REST_Client_Core + Jira_Insight_Server_DC_API_Client -- "inherits from" --> REST_Client_Core + Jira_Xray_API_Client -- "inherits from" --> REST_Client_Core + Jira_Core_Software_API_Client -- "uses" --> API_Error_Handling + Jira_Ecosystem_Clients -- "composes" --> Jira_Service_Desk_API_Client + Jira_Ecosystem_Clients -- "composes" --> Jira_Core_Software_API_Client + Jira_Ecosystem_Clients -- "composes" --> Jira_Assets_Cloud_API_Client + Jira_Ecosystem_Clients -- "composes" --> Jira_Portfolio_API_Client + Jira_Ecosystem_Clients -- "composes" --> Jira_Insight_Server_DC_API_Client + Jira_Ecosystem_Clients -- "composes" --> Jira_Xray_API_Client +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The Jira Ecosystem Clients component serves as a unified interface, abstracting interactions with various Atlassian Jira-related APIs. It consolidates functionalities from Jira Core/Software, Jira Service Desk, Atlassian Assets/Insight, Xray Test Management, and Jira Portfolio/Advanced Roadmaps. This component relies on a foundational REST Client Core for all low-level HTTP communications, which handles authentication, error handling, and retry mechanisms. Individual API clients for each Jira product inherit from or utilize this core client, providing specialized functionalities. The overall flow involves a consumer interacting with the consolidated Jira Ecosystem Clients, which then delegates specific requests to the appropriate underlying API client, leveraging the robust REST Client Core for network operations and standardized error handling. + +### Jira Ecosystem Clients +A consolidated interface for interacting with various Jira-related APIs, including core Jira functionalities (issues, projects, users), Jira Service Desk (customer requests, SLAs), Atlassian Assets/Insight (configuration items), Xray Test Management (tests, test runs), and Jira Portfolio/Advanced Roadmaps (planning data). This component abstracts the specific API calls for these interconnected Jira products. + + +**Related Classes/Methods**: + +- `atlassian.jira.Jira` (19:5794) +- `atlassian.service_desk.ServiceDesk` (11:929) +- `atlassian.assets.AssetsCloud` (11:626) +- `atlassian.insight.Insight` (10:677) +- `atlassian.xray.Xray` (10:662) +- `atlassian.portfolio.Portfolio` (9:108) + + +### REST Client Core +This is the foundational component responsible for handling all low-level HTTP requests (GET, POST, PUT, DELETE, PATCH) to Atlassian REST APIs. It manages authentication (basic, token, OAuth, Kerberos), SSL verification, request timeouts, and implements exponential backoff and retry mechanisms for robust communication. It also provides utility methods for URL construction and response parsing. + + +**Related Classes/Methods**: + +- `atlassian.rest_client.AtlassianRestAPI` (43:1001) + + +### Jira Service Desk API Client +This component provides a high-level interface for interacting with the Jira Service Desk API. It encapsulates specific Service Desk functionalities such as managing service desks, customers, customer requests, comments, organizations, attachments, SLAs, and approvals. It relies on the REST Client Core for all underlying HTTP operations. + + +**Related Classes/Methods**: + +- `atlassian.service_desk.ServiceDesk` (11:929) + + +### Jira Core/Software API Client +This is a comprehensive client for the Jira Core and Jira Software APIs. It offers extensive functionalities for managing issues (create, update, delete, transition, comments, attachments, links, properties, worklogs), projects (create, delete, archive, versions, components, roles, permissions, notifications), users, groups, dashboards, filters, and integrates with Jira Agile (boards, sprints, epics, ranking) and Tempo (accounts, holidays, timesheets, teams). All its interactions with Jira are performed via the REST Client Core. + + +**Related Classes/Methods**: + +- `atlassian.jira.Jira` (19:5794) + + +### Jira Assets Cloud API Client +This component provides an interface for managing Assets (formerly Insight) data within Jira Cloud. It handles operations related to objects, object schemas, attributes, attachments, comments, icons, and import/reindex processes. It extends the REST Client Core and includes specific logic for cloud workspace identification. + + +**Related Classes/Methods**: + +- `atlassian.assets.AssetsCloud` (11:626) + + +### Jira Portfolio API Client +This component is designed to interact with the Jira Portfolio (now Advanced Roadmaps) API. It provides methods to retrieve information about plans, epics, stages, teams, persons, streams, releases, themes, and dependencies. It also supports importing work items and querying issues via JQL for portfolio purposes. It uses the REST Client Core for its API calls. + + +**Related Classes/Methods**: + +- `atlassian.portfolio.Portfolio` (9:108) + + +### Jira Insight Server/DC API Client +This component provides an interface for managing Insight (now Assets) data in Jira Server/Data Center environments. Similar to AssetsCloud, it handles objects, schemas, attributes, attachments, comments, icons, and import/reindex processes, but is tailored for non-cloud deployments. It extends the REST Client Core. + + +**Related Classes/Methods**: + +- `atlassian.insight.Insight` (10:677) + + +### Jira Xray API Client +This component provides a specialized client for the Jira Xray Test Management API. It enables management of tests, test steps, test runs, preconditions, test sets, and test plans. It overrides the base resource_url method to fit Xray's specific API path structure and relies on the REST Client Core for all HTTP requests. + + +**Related Classes/Methods**: + +- `atlassian.xray.Xray` (10:662) + + +### API Error Handling +This component defines custom exception classes (ApiNotFoundError, ApiPermissionError, ApiValueError, ApiConflictError, ApiNotAcceptable) that are raised by the API clients to indicate specific error conditions encountered during API interactions. This allows for more precise error handling by the consumer of the library. + + +**Related Classes/Methods**: + +- `atlassian.errors.ApiNotFoundError` (10:11) +- `atlassian.errors.ApiPermissionError` (14:15) +- `atlassian.errors.ApiValueError` (18:19) +- `atlassian.errors.ApiConflictError` (22:23) +- `atlassian.errors.ApiNotAcceptable` (26:27) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/REST Client Core.md b/.codeboarding/REST Client Core.md new file mode 100644 index 000000000..3ff15da15 --- /dev/null +++ b/.codeboarding/REST Client Core.md @@ -0,0 +1,83 @@ +```mermaid +graph LR + Authentication_Manager["Authentication Manager"] + Request_Handler["Request Handler"] + Response_Processor["Response Processor"] + Retry_Mechanism["Retry Mechanism"] + HTTP_Methods["HTTP Methods"] + Authentication_Manager -- "initializes session for" --> Request_Handler + Request_Handler -- "utilizes" --> Retry_Mechanism + Request_Handler -- "utilizes for error handling" --> Response_Processor + HTTP_Methods -- "invokes" --> Request_Handler + Response_Processor -- "processes responses from" --> Request_Handler + HTTP_Methods -- "parses response via" --> Response_Processor +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The REST Client Core is the foundational component responsible for managing all HTTP communication with Atlassian APIs. It handles various authentication schemes, constructs API URLs, executes HTTP requests with robust retry mechanisms (including exponential backoff and `Retry-After` header support), and processes responses by handling SSL verification, proxy settings, and error conditions. It serves as the underlying layer for all specific Atlassian product API clients, providing a consistent and reliable interface for API interactions. + +### Authentication Manager +Manages various authentication mechanisms (basic, token, OAuth1, OAuth2, Kerberos, custom headers) by configuring the underlying `requests.Session` object. It ensures that all outgoing requests are properly authenticated. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:__init__` (72:202) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_basic_session` (210:211) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_token_session` (213:214) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_oauth_session` (224:232) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_oauth2_session` (234:245) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_kerberos_session` (219:222) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_header_session` (216:217) + + +### Request Handler +Responsible for constructing and executing HTTP requests. It builds the full URL, applies headers, handles request data (JSON, form data, files), and integrates the retry mechanism before sending the request via the `requests.Session`. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:request` (365:446) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:url_joiner` (356:360) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:resource_url` (346:353) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:log_curl_debug` (320:344) + + +### Response Processor +Handles the parsing and error checking of HTTP responses. It attempts to convert responses to JSON and raises specific `HTTPError` exceptions for status codes indicating failure, providing detailed error messages where available. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:raise_for_status` (964:996) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_response_handler` (257:265) + + +### Retry Mechanism +Implements a robust retry strategy for failed HTTP requests. It supports exponential backoff, random jitter, and respects the `Retry-After` header, ensuring that API calls are retried intelligently to handle rate limits and transient errors. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_retry_handler` (288:318) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_calculate_backoff_value` (267:286) + + +### HTTP Methods +Provides a set of high-level, user-friendly methods for common HTTP verbs (GET, POST, PUT, PATCH, DELETE). These methods abstract the complexities of the `request` method, allowing users to perform standard API operations with simplified parameters. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:get` (450:463) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:post` (610:623) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:put` (731:743) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:patch` (832:867) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:delete` (871:882) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Utility & Error Handling.md b/.codeboarding/Utility & Error Handling.md new file mode 100644 index 000000000..8ce17eb2f --- /dev/null +++ b/.codeboarding/Utility & Error Handling.md @@ -0,0 +1,135 @@ +```mermaid +graph LR + JiraAPIClient["JiraAPIClient"] + ConfluenceAPIClient["ConfluenceAPIClient"] + UtilityFunctions["UtilityFunctions"] + RESTAPICore["RESTAPICore"] + APIErrorHandling["APIErrorHandling"] + JiraAPIClient -- "invokes methods from" --> RESTAPICore + JiraAPIClient -- "raises errors from" --> APIErrorHandling + ConfluenceAPIClient -- "invokes methods from" --> RESTAPICore + ConfluenceAPIClient -- "raises errors from" --> APIErrorHandling + ConfluenceAPIClient -- "utilizes" --> UtilityFunctions +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph represents the core components of the Atlassian Python API library, focusing on its interaction with Jira and Confluence, underlying REST API communication, general utility functions, and a structured approach to API error handling. The main flow involves API clients (Jira and Confluence) utilizing a central REST API core for communication and relying on a dedicated error handling component for robust error management. Additionally, the Confluence API client leverages general utility functions for common tasks. + +### JiraAPIClient +This component provides an interface for interacting with the Jira API. It encapsulates methods for retrieving issue details and managing project security schemes, handling specific Jira-related operations. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.jira.Jira:scrap_regex_from_issue` (1804:1841) +- `atlassian-python-api.atlassian.jira.Jira.get_issue` (1163:1195) +- `atlassian-python-api.atlassian.jira.Jira:get_project_issue_security_scheme` (4139:4167) + + +### ConfluenceAPIClient +This component is responsible for all interactions with the Confluence API. It offers a comprehensive set of functionalities including page creation, retrieval, update, and deletion, attachment management, space operations, user and group details, and content templating. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.confluence.Confluence:page_exists` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_child_by_type` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence._get_paged` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_by_title` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_by_id` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_tables_from_page` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:scrap_regex_from_page` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_labels` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_comments` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_pages_by_label` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_pages_from_space_raw` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_draft_pages_from_space_through_cql` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_pages_by_space_ids_confluence_cloud` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:remove_content` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:remove_page` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:create_page` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence._create_body` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_template_by_id` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_content_template` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_blueprints_from_space` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_blueprint_templates` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_templates_from_space` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_content_templates` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:add_comment` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:attach_content` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence.get_page_id` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_attachments_from_content` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:set_page_label` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:remove_page_label` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:history` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:update_page` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence.is_page_content_is_already_updated` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:_insert_to_existing_page` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:set_page_property` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:update_page_property` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:delete_page_property` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_property` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_properties` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_ancestors` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_all_groups` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_group_members` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_space` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_space_content` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:delete_space` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_space_property` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_user_details_by_username` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_user_details_by_accountid` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_user_details_by_userkey` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:cql` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_page_as_pdf` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence.get_pdf_download_url_for_confluence_cloud` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_space_export` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence.get_space_export.get_atl_request` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_descendant_page_id` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:check_long_task_result` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:anonymous` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:get_whiteboard` (full file reference) +- `atlassian-python-api.atlassian.confluence.Confluence:delete_whiteboard` (full file reference) + + +### UtilityFunctions +This component provides a collection of utility functions that assist in common tasks such as generating HTML structures (lists, table rows, and full tables from dictionaries) and validating email addresses. These functions are generally reusable across different parts of the application. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.utils` (full file reference) + + +### RESTAPICore +This is the foundational component for all REST API communications within the Atlassian Python API. It handles the core functionalities of making HTTP requests (GET, POST, PUT, DELETE), constructing resource URLs, and serving as the primary interface for interacting with Atlassian services at a low level. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI.resource_url` (346:353) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI.get` (450:463) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI.post` (610:623) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI.delete` (871:882) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI.put` (731:743) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI.url_joiner` (356:360) + + +### APIErrorHandling +This component defines and manages various custom exception types that represent specific errors encountered during API interactions. It provides a structured way to handle different error scenarios such as not found resources, permission issues, invalid values, and conflicts. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.errors.ApiNotFoundError` (10:11) +- `atlassian-python-api.atlassian.errors.ApiPermissionError` (14:15) +- `atlassian-python-api.atlassian.errors.ApiError` (4:7) +- `atlassian-python-api.atlassian.errors.ApiValueError` (18:19) +- `atlassian-python-api.atlassian.errors.ApiConflictError` (22:23) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 000000000..9d19aabaf --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,162 @@ +```mermaid +graph LR + REST_Client_Core["REST Client Core"] + Jira_Ecosystem_Clients["Jira Ecosystem Clients"] + Confluence_API_Client["Confluence API Client"] + Bitbucket_API_Client["Bitbucket API Client"] + Bamboo_API_Client["Bamboo API Client"] + Atlassian_Platform_Marketplace_Clients["Atlassian Platform & Marketplace Clients"] + Utility_Error_Handling["Utility & Error Handling"] + Jira_Ecosystem_Clients -- "uses" --> REST_Client_Core + Jira_Ecosystem_Clients -- "handles errors with" --> Utility_Error_Handling + Confluence_API_Client -- "uses" --> REST_Client_Core + Confluence_API_Client -- "handles errors with" --> Utility_Error_Handling + Bitbucket_API_Client -- "uses" --> REST_Client_Core + Bitbucket_API_Client -- "handles errors with" --> Utility_Error_Handling + Bamboo_API_Client -- "uses" --> REST_Client_Core + Bamboo_API_Client -- "handles errors with" --> Utility_Error_Handling + Atlassian_Platform_Marketplace_Clients -- "uses" --> REST_Client_Core + Atlassian_Platform_Marketplace_Clients -- "handles errors with" --> Utility_Error_Handling + click REST_Client_Core href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/REST Client Core.md" "Details" + click Jira_Ecosystem_Clients href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/Jira Ecosystem Clients.md" "Details" + click Confluence_API_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/Confluence API Client.md" "Details" + click Bitbucket_API_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/Bitbucket API Client.md" "Details" + click Bamboo_API_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/Bamboo API Client.md" "Details" + click Atlassian_Platform_Marketplace_Clients href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/Atlassian Platform & Marketplace Clients.md" "Details" + click Utility_Error_Handling href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/atlassian-python-api/Utility & Error Handling.md" "Details" +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The `atlassian-python-api` library provides a comprehensive Python interface for interacting with various Atlassian products. The core functionality revolves around a `REST Client Core` that handles all HTTP communication, including authentication, retries, and error handling. Specific API clients for products like Jira, Confluence, Bitbucket, Bamboo, and other Atlassian platform services build upon this core, abstracting the complexities of their respective APIs. The `Utility & Error Handling` component provides common utilities and a structured approach to managing API-related errors across all clients. The main flow involves client applications instantiating specific Atlassian product API clients, which then leverage the `REST Client Core` to perform operations, with errors being managed by the `Utility & Error Handling` component. + +### REST Client Core +The foundational component responsible for handling all HTTP requests and responses with Atlassian APIs. It manages session authentication (basic, token, OAuth1, OAuth2, Kerberos), implements robust retry mechanisms with exponential backoff and `Retry-After` header support, handles SSL verification, proxy settings, and constructs API URLs. It serves as the base for all specific Atlassian product API clients. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI` (43:1001) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:__init__` (72:202) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:request` (365:446) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_retry_handler` (288:318) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_calculate_backoff_value` (267:286) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:raise_for_status` (964:996) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_basic_session` (210:211) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_token_session` (213:214) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_oauth_session` (224:232) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_oauth2_session` (234:245) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:_create_kerberos_session` (219:222) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:url_joiner` (356:360) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:resource_url` (346:353) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:get` (450:463) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:post` (610:623) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:put` (731:743) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:patch` (832:867) +- `atlassian-python-api.atlassian.rest_client.AtlassianRestAPI:delete` (871:882) + + +### Jira Ecosystem Clients +A consolidated interface for interacting with various Jira-related APIs, including core Jira functionalities (issues, projects, users), Jira Service Desk (customer requests, SLAs), Atlassian Assets/Insight (configuration items), Xray Test Management (tests, test runs), and Jira Portfolio/Advanced Roadmaps (planning data). This component abstracts the specific API calls for these interconnected Jira products. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.jira.Jira` (19:5794) +- `atlassian-python-api.atlassian.service_desk.ServiceDesk` (11:929) +- `atlassian-python-api.atlassian.assets.AssetsCloud` (11:626) +- `atlassian-python-api.atlassian.insight.Insight` (10:677) +- `atlassian-python-api.atlassian.xray.Xray` (10:662) +- `atlassian-python-api.atlassian.portfolio.Portfolio` (9:108) + + +### Confluence API Client +Facilitates interaction with the Confluence API, allowing operations on pages, spaces, comments, attachments, labels, content history, templates, and user/group permissions within Confluence. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.confluence.Confluence` (full file reference) + + +### Bitbucket API Client +Provides a unified interface for interacting with both Bitbucket Server and Bitbucket Cloud APIs. This component covers functionalities related to projects, repositories, branches, tags, pull requests, webhooks, users, groups, and various administrative and permission management tasks across both Bitbucket platforms. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.bitbucket.Bitbucket` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.base.BitbucketBase` (14:204) +- `atlassian-python-api.atlassian.bitbucket.cloud.base.BitbucketCloudBase` (11:125) +- `atlassian-python-api.atlassian.bitbucket.cloud.Cloud` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.projects.Projects` (9:120) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.projects.Project` (123:215) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.permissions.Permissions` (7:52) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.permissions.WorkspaceMembership` (55:97) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.permissions.RepositoryPermission` (100:124) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.members.WorkspaceMembers` (6:39) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.members.WorkspaceMember` (42:64) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.Workspaces` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.cloud.workspaces.Workspace` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.cloud.common.users.User` (4:31) +- `atlassian-python-api.atlassian.bitbucket.cloud.common.users.Participant` (34:79) +- `atlassian-python-api.atlassian.bitbucket.cloud.common.builds.Build` (4:86) +- `atlassian-python-api.atlassian.bitbucket.cloud.common.comments.Comment` (5:50) +- `atlassian-python-api.atlassian.bitbucket.server.globalPermissions.GlobalPermissions` (6:103) +- `atlassian-python-api.atlassian.bitbucket.server.globalPermissions.Groups` (106:111) +- `atlassian-python-api.atlassian.bitbucket.server.globalPermissions.Users` (114:119) +- `atlassian-python-api.atlassian.bitbucket.server.globalPermissions.PermissionBase` (122:153) +- `atlassian-python-api.atlassian.bitbucket.server.globalPermissions.Group` (156:164) +- `atlassian-python-api.atlassian.bitbucket.server.globalPermissions.User` (167:198) +- `atlassian-python-api.atlassian.bitbucket.server.base.BitbucketServerBase` (6:63) +- `atlassian-python-api.atlassian.bitbucket.server.Server` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.server.projects.Projects` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.server.projects.Project` (full file reference) +- `atlassian-python-api.atlassian.bitbucket.server.common.permissions.Permissions` (6:107) +- `atlassian-python-api.atlassian.bitbucket.server.common.permissions.Groups` (110:115) +- `atlassian-python-api.atlassian.bitbucket.server.common.permissions.Users` (118:123) +- `atlassian-python-api.atlassian.bitbucket.server.common.permissions.PermissionBase` (126:161) +- `atlassian-python-api.atlassian.bitbucket.server.common.permissions.Group` (164:173) +- `atlassian-python-api.atlassian.bitbucket.server.common.permissions.User` (176:220) + + +### Bamboo API Client +Manages interactions with the Bamboo CI/CD API, covering projects, build plans, branches, build results, deployments, users, groups, permissions, agents, and reports. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.bamboo.Bamboo` (11:1472) + + +### Atlassian Platform & Marketplace Clients +Provides interfaces for interacting with various Atlassian platform-level services and the Marketplace. This includes user and group management via Atlassian Crowd, public status page management through StatusPage, retrieval of application and vendor information from the Atlassian Marketplace, and administrative functions for Atlassian Cloud organizations and user profiles. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.crowd.Crowd` (12:297) +- `atlassian-python-api.atlassian.statuspage.StatusPage` (108:3133) +- `atlassian-python-api.atlassian.marketplace.MarketPlace` (9:84) +- `atlassian-python-api.atlassian.cloud_admin.CloudAdminOrgs` (11:105) +- `atlassian-python-api.atlassian.cloud_admin.CloudAdminUsers` (108:117) + + +### Utility & Error Handling +Contains general utility functions used across the library, such as HTML formatting and email validation. It also defines custom exception classes for handling various API-related errors (e.g., `ApiNotFoundError`, `ApiPermissionError`, `ApiError`, `ApiValueError`, `ApiConflictError`), providing structured error information for robust error management. + + +**Related Classes/Methods**: + +- `atlassian-python-api.atlassian.utils` (full file reference) +- `atlassian-python-api.atlassian.errors.ApiNotFoundError` (10:11) +- `atlassian-python-api.atlassian.errors.ApiPermissionError` (14:15) +- `atlassian-python-api.atlassian.errors.ApiError` (4:7) +- `atlassian-python-api.atlassian.errors.ApiValueError` (18:19) +- `atlassian-python-api.atlassian.errors.ApiConflictError` (22:23) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file