diff --git a/.codeboarding/API Error Handling.md b/.codeboarding/API Error Handling.md new file mode 100644 index 00000000..d0d5ffb1 --- /dev/null +++ b/.codeboarding/API Error Handling.md @@ -0,0 +1,168 @@ +```mermaid +graph LR + Linode_API_Client_Core_["Linode API Client (Core)"] + API_Error_Handling["API Error Handling"] + Authentication_and_Login_Management["Authentication and Login Management"] + Linode_Resource_Group_Interfaces["Linode Resource Group Interfaces"] + Individual_Resource_Objects["Individual Resource Objects"] + Event_Polling_Mechanism["Event Polling Mechanism"] + Linode_API_Client_Core_ -- "raises" --> API_Error_Handling + Authentication_and_Login_Management -- "uses" --> Linode_API_Client_Core_ + Authentication_and_Login_Management -- "invokes" --> API_Error_Handling + Linode_Resource_Group_Interfaces -- "uses" --> Linode_API_Client_Core_ + Linode_Resource_Group_Interfaces -- "invokes" --> API_Error_Handling + Individual_Resource_Objects -- "uses" --> Linode_API_Client_Core_ + Individual_Resource_Objects -- "invokes" --> API_Error_Handling + Event_Polling_Mechanism -- "invokes" --> API_Error_Handling +``` +[![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 system provides a comprehensive Python client for interacting with the Linode API. It encompasses core functionalities such as making authenticated API requests, managing various Linode resources through high-level group interfaces and individual resource objects, handling asynchronous API events, and robustly managing and reporting API-related errors. The client ensures secure access via authentication and token management, offering a structured and reliable way to programmatically control Linode services. + +### Linode API Client (Core) +The central component responsible for making HTTP requests to the Linode API, handling authentication, and managing the session. It includes the fundamental logic for API communication and initial error checking. + + +**Related Classes/Methods**: + +- `linode_api4.linode_client.LinodeClient` (54:488) +- `linode_api4.linode_client.LinodeClient:_api_call` (250:302) +- `linode_api4.linode_client.LinodeClient:_get_objects` (304:333) + + +### API Error Handling +Manages and represents various error types that can be returned by the Linode API, providing structured information for error diagnosis and handling. This component defines and manages the various error types that can be returned by the Linode API, providing methods to parse API responses into specific error objects for consistent error reporting throughout the library. + + +**Related Classes/Methods**: + +- `linode_api4.errors.ApiError` (11:100) +- `linode_api4.errors.ApiError:from_response` (37:100) +- `linode_api4.errors.UnexpectedResponseError` (103:149) +- `linode_api4.errors.UnexpectedResponseError:from_response` (126:149) +- `linode_api4.polling.EventError` (9:26) + + +### Authentication and Login Management +This component specifically handles user authentication flows, including OAuth processes and the refreshing or expiring of access tokens, ensuring secure access to the Linode API. + + +**Related Classes/Methods**: + +- `linode_api4.login_client.LinodeLoginClient` (325:519) +- `linode_api4.login_client.LinodeLoginClient:finish_oauth` (393:447) +- `linode_api4.login_client.LinodeLoginClient:refresh_oauth_token` (449:488) +- `linode_api4.login_client.LinodeLoginClient:expire_token` (490:519) + + +### Linode Resource Group Interfaces +These components serve as high-level interfaces for managing collections of Linode resources. They provide methods for creating, listing, and performing bulk operations on specific resource types like Linodes, Domains, or Volumes. + + +**Related Classes/Methods**: + +- `linode_api4.groups.placement.PlacementAPIGroup:group_create` (34:76) +- `linode_api4.groups.database.DatabaseGroup:mysql_create` (122:184) +- `linode_api4.groups.database.DatabaseGroup:mysql_fork` (186:239) +- `linode_api4.groups.database.DatabaseGroup:postgresql_create` (256:321) +- `linode_api4.groups.database.DatabaseGroup:postgresql_fork` (323:377) +- `linode_api4.groups.tag.TagGroup:create` (28:116) +- `linode_api4.groups.volume.VolumeGroup:create` (28:77) +- `linode_api4.groups.object_storage.ObjectStorageGroup:keys_create` (93:195) +- `linode_api4.groups.object_storage.ObjectStorageGroup:transfer` (278:298) +- `linode_api4.groups.object_storage.ObjectStorageGroup:bucket_create` (345:433) +- `linode_api4.groups.object_storage.ObjectStorageGroup:object_url_create` (447:520) +- `linode_api4.groups.support.SupportGroup:ticket_open` (38:105) +- `linode_api4.groups.domain.DomainGroup:create` (27:61) +- `linode_api4.groups.linode.LinodeGroup:instance_create` (136:356) +- `linode_api4.groups.linode.LinodeGroup:stackscript_create` (392:451) +- `linode_api4.groups.monitor.MonitorGroup:create_token` (123:153) +- `linode_api4.groups.account.AccountGroup:__call__` (29:49) +- `linode_api4.groups.account.AccountGroup:settings` (83:102) +- `linode_api4.groups.account.AccountGroup:oauth_client_create` (143:171) +- `linode_api4.groups.account.AccountGroup:add_payment_method` (228:278) +- `linode_api4.groups.account.AccountGroup:linode_managed_enable` (296:312) +- `linode_api4.groups.account.AccountGroup:add_promo_code` (314:338) +- `linode_api4.groups.account.AccountGroup:service_transfer_create` (352:393) +- `linode_api4.groups.account.AccountGroup:transfer` (395:411) +- `linode_api4.groups.account.AccountGroup:user_create` (413:456) +- `linode_api4.groups.lke.LKEGroup:cluster_create` (61:149) +- `linode_api4.groups.image.ImageGroup:create` (33:83) +- `linode_api4.groups.image.ImageGroup:create_upload` (85:132) +- `linode_api4.groups.nodebalancer.NodeBalancerGroup:create` (27:52) +- `linode_api4.groups.longview.LongviewGroup:client_create` (31:55) +- `linode_api4.groups.vpc.VPCGroup:create` (30:82) +- `linode_api4.groups.profile.ProfileGroup:__call__` (23:44) +- `linode_api4.groups.profile.ProfileGroup:phone_number_delete` (119:139) +- `linode_api4.groups.profile.ProfileGroup:phone_number_verify` (141:172) +- `linode_api4.groups.profile.ProfileGroup:phone_number_verification_code_send` (174:210) +- `linode_api4.groups.profile.ProfileGroup:token_create` (238:272) +- `linode_api4.groups.profile.ProfileGroup:ssh_key_upload` (304:345) +- `linode_api4.groups.networking.NetworkingGroup:firewall_create` (36:95) +- `linode_api4.groups.networking.NetworkingGroup:ip_allocate` (215:245) + + +### Individual Resource Objects +These components represent specific instances of Linode resources (e.g., a particular Linode Instance or a Volume). They provide methods to interact with and modify the state of that individual resource via the API. + + +**Related Classes/Methods**: + +- `linode_api4.objects.volume.Volume:attach` (57:89) +- `linode_api4.objects.volume.Volume:clone` (126:147) +- `linode_api4.objects.object_storage.ObjectStorageBucket:make_instance` (114:127) +- `linode_api4.objects.object_storage.ObjectStorageBucket:access_get` (129:152) +- `linode_api4.objects.object_storage.ObjectStorageBucket:access_modify` (154:193) +- `linode_api4.objects.object_storage.ObjectStorageBucket:access_update` (195:234) +- `linode_api4.objects.object_storage.ObjectStorageBucket:ssl_cert_delete` (236:257) +- `linode_api4.objects.object_storage.ObjectStorageBucket:ssl_cert` (259:282) +- `linode_api4.objects.object_storage.ObjectStorageBucket:ssl_cert_upload` (284:325) +- `linode_api4.objects.object_storage.ObjectStorageBucket:contents` (327:391) +- `linode_api4.objects.object_storage.ObjectStorageBucket:object_acl_config` (393:428) +- `linode_api4.objects.object_storage.ObjectStorageBucket:object_acl_config_update` (430:471) +- `linode_api4.objects.support.SupportTicket:post_reply` (116:143) +- `linode_api4.objects.support.SupportTicket:upload_attachment` (145:181) +- `linode_api4.objects.domain.Domain:record_create` (62:98) +- `linode_api4.objects.linode.Disk:duplicate` (full file reference) +- `linode_api4.objects.linode.Config:_interface_create` (full file reference) +- `linode_api4.objects.linode.Instance:ips` (full file reference) +- `linode_api4.objects.linode.Instance:available_backups` (full file reference) +- `linode_api4.objects.linode.Instance:transfer` (full file reference) +- `linode_api4.objects.linode.Instance:config_create` (full file reference) +- `linode_api4.objects.linode.Instance:disk_create` (full file reference) +- `linode_api4.objects.linode.Instance:snapshot` (full file reference) +- `linode_api4.objects.linode.Instance:ip_allocate` (full file reference) +- `linode_api4.objects.linode.Instance:rebuild` (full file reference) +- `linode_api4.objects.linode.Instance:clone` (full file reference) +- `linode_api4.objects.account.ChildAccount:create_token` (71:89) +- `linode_api4.objects.account.ServiceTransfer:service_transfer_accept` (111:127) +- `linode_api4.objects.account.PaymentMethod:payment_method_make_default` (146:162) +- `linode_api4.objects.account.OAuthClient:reset_secret` (409:425) +- `linode_api4.objects.account.OAuthClient:thumbnail` (427:455) +- `linode_api4.objects.account.OAuthClient:set_thumbnail` (457:488) +- `linode_api4.objects.region.Region:availability` (41:51) +- `linode_api4.objects.lke.LKECluster:node_pool_create` (412:478) +- `linode_api4.objects.nodebalancer.NodeBalancerConfig:node_create` (157:198) +- `linode_api4.objects.nodebalancer.NodeBalancer:config_create` (258:284) +- `linode_api4.objects.nodebalancer.NodeBalancer:config_rebuild` (286:320) +- `linode_api4.objects.nodebalancer.NodeBalancer:statistics` (322:339) +- `linode_api4.objects.vpc.VPC:subnet_create` (63:101) +- `linode_api4.objects.profile.Profile:add_whitelist_entry` (166:186) +- `linode_api4.objects.networking.IPAddress:ip_allocate` (full file reference) +- `linode_api4.objects.networking.Firewall:device_create` (278:307) + + +### Event Polling Mechanism +This component is dedicated to monitoring and reacting to asynchronous events from the Linode API, allowing the client to wait for specific event completions or handle event-related errors. + + +**Related Classes/Methods**: + +- `linode_api4.polling.EventPoller:wait_for_next_event_finished` (215:250) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/API Resource Data Models.md b/.codeboarding/API Resource Data Models.md new file mode 100644 index 00000000..ee52c757 --- /dev/null +++ b/.codeboarding/API Resource Data Models.md @@ -0,0 +1,217 @@ +```mermaid +graph LR + API_Client["API Client"] + API_Resource_Groups["API Resource Groups"] + API_Resource_Data_Models["API Resource Data Models"] + Pagination_Handler["Pagination Handler"] + Filtering_Module["Filtering Module"] + Serialization_and_Deserialization["Serialization and Deserialization"] + Utility_Functions["Utility Functions"] + Error_Handling["Error Handling"] + Polling_Mechanism["Polling Mechanism"] + API_Client -- "initializes and uses" --> API_Resource_Groups + API_Resource_Groups -- "creates and manages" --> API_Resource_Data_Models + API_Client -- "returns" --> Pagination_Handler + API_Client -- "uses for queries" --> Filtering_Module + API_Client -- "uses for data conversion" --> Serialization_and_Deserialization + API_Client -- "uses for data preparation" --> Utility_Functions + API_Client -- "raises" --> Error_Handling + API_Client -- "monitors events via" --> Polling_Mechanism + API_Resource_Data_Models -- "inherits from" --> Serialization_and_Deserialization + API_Resource_Data_Models -- "uses for data manipulation" --> Utility_Functions + Filtering_Module -- "generates" --> Filtering_Module + Serialization_and_Deserialization -- "processes data for" --> API_Resource_Data_Models + Utility_Functions -- "processes data for" --> API_Resource_Data_Models + Utility_Functions -- "processes data for" --> API_Resource_Groups + Error_Handling -- "handles errors from" --> API_Client + Pagination_Handler -- "provides data to" --> API_Resource_Data_Models + API_Resource_Data_Models -- "invokes" --> 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 + +This graph provides an overview of the `API Resource Data Models` component within the `python-linode-api` project, detailing its structure, purpose, and interactions with other key components. The `API Resource Data Models` component defines concrete data models for various Linode API resources, extending core API data models to include resource-specific attributes and methods. It interacts with the `API Client` for performing actions on resources, relies on `Serialization and Deserialization` for data conversion, and utilizes `Utility Functions` for data manipulation. The overall flow involves the `API Client` initializing and using `API Resource Groups`, which in turn create and manage instances of `API Resource Data Models`. The `API Client` also handles pagination through the `Pagination Handler`, uses the `Filtering Module` for queries, and incorporates `Error Handling` for robust operation. The `Polling Mechanism` allows for monitoring asynchronous API events. + +### API Client +The central interface for interacting with the Linode API. It manages authentication, constructs and sends HTTP requests, handles retries, and provides access to various API resource groups. It also includes methods for loading specific API objects and handling paginated responses. + + +**Related Classes/Methods**: + +- `linode_api4.linode_client.LinodeClient` (54:488) +- `linode_api4.linode_client._api_call` (full file reference) +- `linode_api4.linode_client._get_objects` (full file reference) +- `linode_api4.linode_client.get` (full file reference) +- `linode_api4.linode_client.post` (full file reference) +- `linode_api4.linode_client.put` (full file reference) +- `linode_api4.linode_client.delete` (full file reference) +- `linode_api4.linode_client.load` (full file reference) + + +### API Resource Groups +These classes organize and encapsulate methods for managing specific Linode API resources, such as Linodes, Databases, Accounts, and Domains. They act as facades, providing a structured way to interact with different parts of the Linode API through the main API Client. + + +**Related Classes/Methods**: + +- `linode_api4.groups.placement.PlacementAPIGroup.group_create` (34:76) +- `linode_api4.groups.database.DatabaseGroup.mysql_create` (122:184) +- `linode_api4.groups.database.DatabaseGroup.postgresql_create` (256:321) +- `linode_api4.groups.tag.TagGroup.create` (28:116) +- `linode_api4.groups.volume.VolumeGroup.create` (28:77) +- `linode_api4.groups.object_storage.ObjectStorageGroup.keys_create` (93:195) +- `linode_api4.groups.support.SupportGroup.ticket_open` (38:105) +- `linode_api4.groups.domain.DomainGroup.create` (27:61) +- `linode_api4.groups.linode.LinodeGroup.instance_create` (136:356) +- `linode_api4.groups.linode.LinodeGroup.stackscript_create` (392:451) +- `linode_api4.groups.account.AccountGroup.__call__` (29:49) +- `linode_api4.groups.lke.LKEGroup.cluster_create` (61:149) +- `linode_api4.groups.image.ImageGroup.create` (33:83) +- `linode_api4.groups.nodebalancer.NodeBalancerGroup.create` (27:52) +- `linode_api4.groups.profile.ProfileGroup.__call__` (23:44) +- `linode_api4.groups.networking.NetworkingGroup.firewall_create` (36:95) + + +### API Resource Data Models +Concrete data models representing various Linode API resources such as Linode instances, databases, object storage, networking components, LKE clusters, NodeBalancers, account details, user profiles, domains, volumes, images, tags, support tickets, placement groups, and regions. These models extend `linode_api4.objects.base.Base` (the core API data model) and `linode_api4.objects.serializable.JSONObject` to provide resource-specific attributes and methods, and facilitate serialization and deserialization. They provide properties to access resource attributes and methods to perform actions on the specific resource, such as updating, deleting, or performing resource-specific operations. + + +**Related Classes/Methods**: + +- `linode_api4.objects.base.Base` (147:506) +- `linode_api4.objects.base.Base.save` (254:295) +- `linode_api4.objects.base.Base.delete` (297:306) +- `linode_api4.objects.base.Base.invalidate` (308:320) +- `linode_api4.objects.base.Base._api_get` (355:360) +- `linode_api4.objects.base.Base._populate` (362:453) +- `linode_api4.objects.dbase.DerivedBase` (4:27) +- `linode_api4.objects.serializable.JSONObject` (43:258) +- `linode_api4.objects.linode.Instance` (full file reference) +- `linode_api4.objects.linode.Backup` (full file reference) +- `linode_api4.objects.linode.Disk` (full file reference) +- `linode_api4.objects.linode.Config` (full file reference) +- `linode_api4.objects.linode.NetworkInterface` (full file reference) +- `linode_api4.objects.linode.StackScript` (full file reference) +- `linode_api4.objects.linode.Type` (full file reference) +- `linode_api4.objects.linode.UserDefinedField` (full file reference) +- `linode_api4.objects.database.DatabaseType` (15:44) +- `linode_api4.objects.database.DatabaseEngine` (47:74) +- `linode_api4.objects.database.MySQLDatabase` (274:436) +- `linode_api4.objects.database.PostgreSQLDatabase` (439:603) +- `linode_api4.objects.database.Database` (612:670) +- `linode_api4.objects.object_storage.ObjectStorageBucket` (82:502) +- `linode_api4.objects.object_storage.ObjectStorageKeys` (561:578) +- `linode_api4.objects.object_storage.ObjectStorageQuota` (581:616) +- `linode_api4.objects.networking.Firewall` (198:307) +- `linode_api4.objects.networking.IPAddress` (60:127) +- `linode_api4.objects.networking.IPv6Range` (26:45) +- `linode_api4.objects.networking.FirewallDevice` (179:195) +- `linode_api4.objects.lke.LKECluster` (267:639) +- `linode_api4.objects.lke.LKENodePool` (173:264) +- `linode_api4.objects.lke.LKENodePoolNode` (147:170) +- `linode_api4.objects.nodebalancer.NodeBalancer` (232:357) +- `linode_api4.objects.nodebalancer.NodeBalancerConfig` (75:229) +- `linode_api4.objects.nodebalancer.NodeBalancerNode` (30:72) +- `linode_api4.objects.account.Account` (25:56) +- `linode_api4.objects.account.AccountSettings` (183:201) +- `linode_api4.objects.account.ChildAccount` (59:89) +- `linode_api4.objects.account.Event` (204:331) +- `linode_api4.objects.account.InvoiceItem` (334:366) +- `linode_api4.objects.account.OAuthClient` (390:488) +- `linode_api4.objects.account.PaymentMethod` (130:162) +- `linode_api4.objects.account.ServiceTransfer` (92:127) +- `linode_api4.objects.account.User` (507:555) +- `linode_api4.objects.account.UserGrants` (619:703) +- `linode_api4.objects.account.Grant` (577:616) +- `linode_api4.objects.profile.Profile` (59:186) +- `linode_api4.objects.profile.PersonalAccessToken` (25:41) +- `linode_api4.objects.profile.SSHKey` (189:203) +- `linode_api4.objects.profile.WhitelistEntry` (44:56) +- `linode_api4.objects.domain.Domain` (34:160) +- `linode_api4.objects.domain.DomainRecord` (5:31) +- `linode_api4.objects.volume.Volume` (31:147) +- `linode_api4.objects.image.Image` (33:89) +- `linode_api4.objects.tag.Tag` (19:79) +- `linode_api4.objects.tag.TaggedObjectProxy` (82:132) +- `linode_api4.objects.support.SupportTicket` (39:190) +- `linode_api4.objects.support.TicketReply` (18:36) +- `linode_api4.objects.placement.PlacementGroup` (57:128) +- `linode_api4.objects.region.Region` (19:51) + + +### Pagination Handler +This component is responsible for managing and iterating over paginated results returned by the Linode API. It constructs `PaginatedList` objects that allow users to easily access data across multiple pages without manually handling pagination logic. + + +**Related Classes/Methods**: + +- `linode_api4.paginated_list.PaginatedList` (6:262) +- `linode_api4.paginated_list.PaginatedList.make_paginated_list` (230:262) + + +### Filtering Module +This module provides classes and methods for constructing complex filters that can be applied to API queries. It allows users to define conditions for filtering resources based on various attributes, supporting logical operations like AND and OR. + + +**Related Classes/Methods**: + +- `linode_api4.objects.filtering.order_by` (85:102) +- `linode_api4.objects.filtering.limit` (105:119) +- `linode_api4.objects.filtering.Filter.__or__` (133:139) +- `linode_api4.objects.filtering.Filter.__and__` (141:147) +- `linode_api4.objects.filtering.FilterableAttribute.__eq__` (180:181) +- `linode_api4.objects.filtering.FilterableAttribute.contains` (188:189) +- `linode_api4.objects.filtering.FilterableMetaclass.__init__` (246:251) + + +### Serialization and Deserialization +This component handles the conversion of Python objects to and from JSON format, which is essential for communicating with the RESTful Linode API. It ensures that data sent in requests is correctly formatted and that responses are parsed into usable Python objects. + + +**Related Classes/Methods**: + +- `linode_api4.objects.serializable.JSONObject` (43:258) +- `linode_api4.objects.serializable.JSONObject.from_json` (149:167) +- `linode_api4.objects.serializable.JSONObject.dict` (238:242) +- `linode_api4.objects.serializable.JSONObject._serialize` (169:235) +- `linode_api4.objects.serializable.JSONObject._unwrap_type` (89:101) +- `linode_api4.objects.serializable.JSONObject._try_from_json` (104:114) +- `linode_api4.objects.serializable.JSONObject._parse_attr_list` (117:133) +- `linode_api4.objects.serializable.JSONObject._parse_attr` (136:146) + + +### Utility Functions +This component provides various helper functions that perform common data manipulation tasks, such as removing null keys from dictionaries or flattening request bodies. These utilities support the main API interaction logic by preparing data for requests. + + +**Related Classes/Methods**: + +- `linode_api4.util.drop_null_keys` (8:29) +- `linode_api4.objects.base._flatten_request_body_recursive` (509:535) +- `linode_api4.common.load_and_validate_keys` (16:62) + + +### Error Handling +This component defines and manages custom exceptions for API-related errors, such as unexpected responses from the server. It ensures that specific error conditions are caught and handled gracefully, providing meaningful feedback to the user. + + +**Related Classes/Methods**: + +- `linode_api4.errors.ApiError` (11:100) +- `linode_api4.errors.UnexpectedResponseError` (103:149) + + +### Polling Mechanism +This component provides functionality for polling Linode API events, allowing the client to wait for specific events to occur or for operations to complete. It is crucial for asynchronous operations where the client needs to monitor the status of a resource. + + +**Related Classes/Methods**: + +- `linode_api4.polling.EventPoller.wait_for_next_event` (171:213) +- `linode_api4.polling.EventPoller.wait_for_next_event_finished` (215:250) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/API Resource Group Managers.md b/.codeboarding/API Resource Group Managers.md new file mode 100644 index 00000000..483f9fb2 --- /dev/null +++ b/.codeboarding/API Resource Group Managers.md @@ -0,0 +1,141 @@ +```mermaid +graph LR + APIGroupManagers["APIGroupManagers"] + APIDataModels["APIDataModels"] + RequestDataProcessors["RequestDataProcessors"] + APIErrorHandling["APIErrorHandling"] + AsynchronousPolling["AsynchronousPolling"] + CoreUtilities["CoreUtilities"] + APIFiltering["APIFiltering"] + APIGroupManagers -- "creates/manages" --> APIDataModels + APIGroupManagers -- "uses" --> RequestDataProcessors + APIGroupManagers -- "raises" --> APIErrorHandling + APIGroupManagers -- "initiates" --> AsynchronousPolling + APIGroupManagers -- "leverages" --> CoreUtilities + APIGroupManagers -- "applies" --> APIFiltering +``` +[![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 component comprises classes that serve as the primary interface for interacting with specific Linode API resources. Each class within this component encapsulates methods for creating, retrieving, updating, and deleting resources related to a particular Linode service, such as Databases, Linodes, or Object Storage. + +### APIGroupManagers +This component comprises classes that serve as the primary interface for interacting with specific Linode API resources. Each class within this component encapsulates methods for creating, retrieving, updating, and deleting resources related to a particular Linode service, such as Databases, Linodes, or Object Storage. + + +**Related Classes/Methods**: + +- `linode_api4.groups.linode.LinodeGroup` (29:451) +- `linode_api4.groups.profile.ProfileGroup` (18:345) +- `linode_api4.groups.account.AccountGroup` (24:512) +- `linode_api4.groups.networking.NetworkingGroup` (16:396) +- `linode_api4.groups.support.SupportGroup` (17:105) +- `linode_api4.groups.longview.LongviewGroup` (10:107) +- `linode_api4.groups.object_storage.ObjectStorageGroup` (29:535) +- `linode_api4.groups.lke.LKEGroup` (17:207) +- `linode_api4.groups.database.DatabaseGroup` (20:377) +- `linode_api4.groups.nodebalancer.NodeBalancerGroup` (6:70) +- `linode_api4.groups.domain.DomainGroup` (6:61) +- `linode_api4.groups.tag.TagGroup` (6:116) +- `linode_api4.groups.volume.VolumeGroup` (7:95) +- `linode_api4.groups.region.RegionGroup` (6:45) +- `linode_api4.groups.image.ImageGroup` (12:173) +- `linode_api4.groups.vpc.VPCGroup` (9:104) +- `linode_api4.groups.polling.PollingGroup` (9:91) +- `linode_api4.groups.beta.BetaProgramGroup` (5:24) +- `linode_api4.groups.placement.PlacementAPIGroup` (13:76) +- `linode_api4.groups.monitor.MonitorGroup` (19:153) +- `linode_api4.groups.lke_tier.LKETierGroup` (5:40) + + +### APIDataModels +This component consists of classes that represent the various data structures and entities returned by the Linode API. Instances of these classes hold the retrieved API data and may include methods for further interaction or manipulation of that data. + + +**Related Classes/Methods**: + +- `linode_api4.objects.placement.PlacementGroup` (57:128) +- `linode_api4.objects.database.MySQLDatabase` (274:436) +- `linode_api4.objects.database.PostgreSQLDatabase` (439:603) +- `linode_api4.objects.tag.Tag` (19:79) +- `linode_api4.objects.volume.Volume` (31:147) +- `linode_api4.objects.object_storage.ObjectStorageKeys` (561:578) +- `linode_api4.objects.base.MappedObject` (73:144) +- `linode_api4.objects.object_storage.ObjectStorageBucket` (82:502) +- `linode_api4.objects.support.SupportTicket` (39:190) +- `linode_api4.objects.domain.Domain` (34:160) +- `linode_api4.objects.linode.Instance.generate_root_password` (full file reference) +- `linode_api4.objects.linode.Instance` (full file reference) +- `linode_api4.objects.linode.StackScript` (full file reference) +- `linode_api4.objects.monitor.MonitorServiceToken` (173:180) +- `linode_api4.objects.account.Account` (25:56) +- `linode_api4.objects.account.Event` (204:331) +- `linode_api4.objects.account.AccountSettings` (183:201) +- `linode_api4.objects.account.OAuthClient` (390:488) +- `linode_api4.objects.account.User` (507:555) +- `linode_api4.objects.lke.LKECluster` (267:639) +- `linode_api4.objects.image.Image` (33:89) +- `linode_api4.objects.nodebalancer.NodeBalancer` (232:357) +- `linode_api4.objects.longview.LongviewClient` (4:21) +- `linode_api4.objects.longview.LongviewPlan` (41:55) +- `linode_api4.objects.vpc.VPC` (44:116) +- `linode_api4.objects.profile.Profile` (59:186) +- `linode_api4.objects.profile.PersonalAccessToken` (25:41) +- `linode_api4.objects.profile.SSHKey` (189:203) +- `linode_api4.objects.networking.Firewall` (198:307) +- `linode_api4.objects.networking.IPAddress` (60:127) + + +### RequestDataProcessors +This component includes utility functions responsible for preparing and transforming request bodies before they are sent to the Linode API. This often involves flattening nested data structures or removing null values to conform to API requirements. + + +**Related Classes/Methods**: + +- `linode_api4.objects.base._flatten_request_body_recursive` (509:535) +- `linode_api4.util.drop_null_keys` (8:29) +- `linode_api4.objects.linode._expand_placement_group_assignment` (full file reference) + + +### APIErrorHandling +This component is dedicated to managing and raising exceptions that occur during interactions with the Linode API. It provides a standardized way to signal unexpected responses or errors encountered during API calls. + + +**Related Classes/Methods**: + +- `linode_api4.errors.UnexpectedResponseError` (103:149) + + +### AsynchronousPolling +This component provides mechanisms for asynchronously monitoring the status of Linode resources or events. It includes classes and functions for creating event pollers and managing timeouts while waiting for specific conditions to be met. + + +**Related Classes/Methods**: + +- `linode_api4.polling.EventPoller` (97:250) +- `linode_api4.polling.TimeoutContext` (29:94) +- `linode_api4.groups.polling.PollingGroup.wait_for_entity_free.poll_func` (full file reference) + + +### CoreUtilities +This component encompasses general-purpose utility functions that are utilized across various parts of the Linode API client. These utilities provide common functionalities like key validation or other helper operations. + + +**Related Classes/Methods**: + +- `linode_api4.common.load_and_validate_keys` (16:62) + + +### APIFiltering +This component provides the functionality for constructing and applying filters to retrieve specific subsets of data from Linode API collections. It enables users to refine their API queries based on various criteria. + + +**Related Classes/Methods**: + +- `linode_api4.objects.filtering.Filter` (122:173) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/API Utilities.md b/.codeboarding/API Utilities.md new file mode 100644 index 00000000..ce809cb4 --- /dev/null +++ b/.codeboarding/API Utilities.md @@ -0,0 +1,196 @@ +```mermaid +graph LR + LinodeClientCore["LinodeClientCore"] + APIResourceManagement["APIResourceManagement"] + APIObjectRepresentation["APIObjectRepresentation"] + DataFiltering["DataFiltering"] + PaginationHandling["PaginationHandling"] + PollingMechanism["PollingMechanism"] + OAuthLogin["OAuthLogin"] + UtilityFunctions["UtilityFunctions"] + ErrorHandling["ErrorHandling"] + LinodeClientCore -- "manages" --> APIResourceManagement + LinodeClientCore -- "retrieves_data_with" --> PaginationHandling + LinodeClientCore -- "applies" --> DataFiltering + LinodeClientCore -- "reports" --> ErrorHandling + APIResourceManagement -- "creates_and_modifies" --> APIObjectRepresentation + APIResourceManagement -- "uses" --> UtilityFunctions + APIObjectRepresentation -- "performs_actions_via" --> LinodeClientCore + APIObjectRepresentation -- "utilizes" --> UtilityFunctions + APIObjectRepresentation -- "supports" --> DataFiltering + PollingMechanism -- "monitors" --> APIObjectRepresentation + PollingMechanism -- "handles" --> ErrorHandling + OAuthLogin -- "encounters" --> ErrorHandling + PaginationHandling -- "generates" --> APIObjectRepresentation +``` +[![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 section of the Linode API client library provides a comprehensive suite of utility components designed to streamline various aspects of API interaction. It encompasses mechanisms for asynchronous event polling, secure user authentication via OAuth, efficient handling of large datasets through pagination, flexible data retrieval using advanced filtering capabilities, and a collection of general-purpose helper functions. Together, these components abstract away common complexities, enabling developers to build robust and efficient applications that interact seamlessly with the Linode API. + +### LinodeClientCore +This component serves as the primary interface for interacting with the Linode API. It manages authentication, constructs API requests, handles responses, and provides methods for retrieving single or paginated lists of API objects. It also incorporates retry logic for transient errors. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.linode_client.LinodeClient` (54:488) +- `python-linode-api.linode_api4.linode_client.LinodeClient:_get_objects` (304:333) +- `python-linode-api.linode_api4.linode_client.LinodeClient:_get_and_filter` (461:488) + + +### APIResourceManagement +This component comprises various "group" classes that provide a structured way to interact with different categories of Linode API resources. Each group offers methods tailored to the management of its respective resource type, abstracting away the underlying API endpoints and request complexities. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.groups.database.DatabaseGroup` (20:377) +- `python-linode-api.linode_api4.groups.volume.VolumeGroup` (7:95) +- `python-linode-api.linode_api4.groups.object_storage.ObjectStorageGroup` (29:535) +- `python-linode-api.linode_api4.groups.linode.LinodeGroup` (29:451) +- `python-linode-api.linode_api4.groups.lke.LKEGroup` (17:207) +- `python-linode-api.linode_api4.groups.image.ImageGroup` (12:173) +- `python-linode-api.linode_api4.groups.database.DatabaseGroup:mysql_create` (122:184) +- `python-linode-api.linode_api4.groups.database.DatabaseGroup:mysql_fork` (186:239) +- `python-linode-api.linode_api4.groups.database.DatabaseGroup:postgresql_create` (256:321) +- `python-linode-api.linode_api4.groups.database.DatabaseGroup:postgresql_fork` (323:377) +- `python-linode-api.linode_api4.groups.volume.VolumeGroup:create` (28:77) +- `python-linode-api.linode_api4.groups.object_storage.ObjectStorageGroup:object_url_create` (447:520) +- `python-linode-api.linode_api4.groups.linode.LinodeGroup:stackscripts` (78:117) +- `python-linode-api.linode_api4.groups.linode.LinodeGroup:instance_create` (136:356) +- `python-linode-api.linode_api4.groups.lke.LKEGroup:cluster_create` (61:149) +- `python-linode-api.linode_api4.groups.image.ImageGroup:create` (33:83) +- `python-linode-api.linode_api4.groups.image.ImageGroup:create_upload` (85:132) + + +### APIObjectRepresentation +This component consists of classes that mirror the structure and behavior of resources available through the Linode API. Instances of these classes allow developers to interact with Linode entities (like Linode instances, disks, volumes, or LKE clusters) as Python objects, providing methods for actions specific to each resource. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.objects.tag.Tag` (19:79) +- `python-linode-api.linode_api4.objects.volume.Volume` (31:147) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageBucket` (82:502) +- `python-linode-api.linode_api4.objects.linode.Disk` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance` (full file reference) +- `python-linode-api.linode_api4.objects.lke.LKECluster` (267:639) +- `python-linode-api.linode_api4.objects.lke.LKENodePool` (173:264) +- `linode_api4.objects.account.Event` (204:331) +- `linode_api4.objects.base.Base` (147:506) +- `linode_api4.objects.base.MappedObject` (73:144) +- `linode_api4.objects.database.MySQLDatabase` (274:436) +- `linode_api4.objects.database.PostgreSQLDatabase` (439:603) +- `linode_api4.objects.image.Image` (33:89) +- `python-linode-api.linode_api4.objects.tag.Tag:objects` (62:79) +- `python-linode-api.linode_api4.objects.volume.Volume:attach` (57:89) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageBucket:access_modify` (154:193) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageBucket:access_update` (195:234) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageBucket:contents` (327:391) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageBucket:object_acl_config` (393:428) +- `python-linode-api.linode_api4.objects.linode.Disk:reset_root_password` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance:reset_instance_root_password` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance:generate_root_password` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance:disk_create` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance:rebuild` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance:initiate_migration` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Instance:clone` (full file reference) +- `python-linode-api.linode_api4.objects.lke.LKECluster:node_pool_create` (412:478) +- `python-linode-api.linode_api4.objects.lke.LKECluster:control_plane_acl_update` (596:623) + + +### DataFiltering +This component offers a flexible mechanism for filtering data returned by the Linode API. It includes classes and methods that enable the creation of complex filter expressions, which can then be applied to API requests to narrow down results based on specific criteria. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.objects.filtering:order_by` (85:102) +- `python-linode-api.linode_api4.objects.filtering:limit` (105:119) +- `python-linode-api.linode_api4.objects.filtering.Filter:__or__` (133:139) +- `python-linode-api.linode_api4.objects.filtering.Filter:__and__` (141:147) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:__eq__` (180:181) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:__ne__` (183:184) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:contains` (188:189) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:__gt__` (191:192) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:__lt__` (194:195) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:__ge__` (197:198) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute:__le__` (200:201) +- `python-linode-api.linode_api4.objects.filtering.FilterableMetaclass:__init__` (246:251) +- `python-linode-api.linode_api4.objects.serializable.JSONFilterableMetaclass:__init__` (27:39) +- `linode_api4.objects.filtering.and_` (69:82) +- `linode_api4.objects.filtering.Filter` (122:173) + + +### PaginationHandling +This component is responsible for abstracting the complexities of paginated API responses. It provides methods to construct and manage lists of objects that are retrieved in pages from the API, allowing for seamless iteration over potentially large collections of resources. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.paginated_list.PaginatedList` (6:262) +- `python-linode-api.linode_api4.paginated_list.PaginatedList:_load_page` (100:119) +- `python-linode-api.linode_api4.paginated_list.PaginatedList:__getitem__` (121:141) +- `python-linode-api.linode_api4.paginated_list.PaginatedList:make_paginated_list` (230:262) +- `python-linode-api.linode_api4.paginated_list.PaginatedList:make_list` (195:227) + + +### PollingMechanism +This component provides functionality for asynchronously monitoring the status of Linode API events or entities. It allows the client to wait for specific conditions to be met, such as an event completing or an entity transitioning to a desired state, without blocking the main application thread. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.polling.EventPoller` (97:250) +- `python-linode-api.linode_api4.polling.EventPoller:__init__` (102:122) +- `python-linode-api.linode_api4.polling.EventPoller:wait_for_next_event` (171:213) +- `python-linode-api.linode_api4.polling.EventPoller:wait_for_next_event_finished` (215:250) +- `python-linode-api.linode_api4.groups.polling.PollingGroup:event_poller_create` (14:43) +- `python-linode-api.linode_api4.groups.polling.PollingGroup:wait_for_entity_free` (45:91) +- `python-linode-api.linode_api4.polling.TimeoutContext` (29:94) + + +### OAuthLogin +This component manages the process of authenticating users with the Linode API using OAuth 2.0. It provides methods for generating login URLs, exchanging authorization codes for access tokens, and refreshing expired tokens, ensuring secure user access. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.login_client.OAuthScopes:parse` (277:299) +- `python-linode-api.linode_api4.login_client.LinodeLoginClient:generate_login_url` (357:391) +- `python-linode-api.linode_api4.login_client.LinodeLoginClient:finish_oauth` (393:447) +- `python-linode-api.linode_api4.login_client.LinodeLoginClient:refresh_oauth_token` (449:488) +- `python-linode-api.linode_api4.login_client.LinodeLoginClient:expire_token` (490:519) +- `python-linode-api.linode_api4.login_client.LinodeLoginClient` (325:519) +- `python-linode-api.linode_api4.login_client.OAuthScopes` (22:322) + + +### UtilityFunctions +This component groups various utility functions that perform common tasks such as data manipulation (e.g., removing null keys from dictionaries) or password generation. These functions support the broader functionality of the Linode API client. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.util:drop_null_keys` (8:29) +- `linode_api4.objects.base._flatten_request_body_recursive` (509:535) +- `linode_api4.common.load_and_validate_keys` (16:62) +- `python-linode-api.linode_api4.objects.linode.Instance.generate_root_password._func` (full file reference) +- `python-linode-api.linode_api4.objects.linode._expand_placement_group_assignment` (full file reference) + + +### ErrorHandling +This component defines custom exception types and utility methods for parsing and raising errors encountered during interactions with the Linode API. It ensures that API-specific error messages are properly captured and communicated to the user. + + +**Related Classes/Methods**: + +- `linode_api4.errors.ApiError.from_response` (37:100) +- `linode_api4.errors.UnexpectedResponseError` (103:149) +- `python-linode-api.linode_api4.polling.EventError` (9:26) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Core API Data Models.md b/.codeboarding/Core API Data Models.md new file mode 100644 index 00000000..0f249f69 --- /dev/null +++ b/.codeboarding/Core API Data Models.md @@ -0,0 +1,68 @@ +```mermaid +graph LR + Base_API_Object["Base API Object"] + Mapped_Object_Utility["Mapped Object Utility"] + JSON_Serialization["JSON Serialization"] + Request_Body_Flattening["Request Body Flattening"] + Derived_Base_Object["Derived Base Object"] + Derived_Base_Object -- "inherits from" --> Base_API_Object + Base_API_Object -- "utilizes" --> Mapped_Object_Utility + Base_API_Object -- "utilizes" --> JSON_Serialization + Request_Body_Flattening -- "processes data for" --> Base_API_Object + Request_Body_Flattening -- "processes data for" --> Mapped_Object_Utility +``` +[![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 component overview describes the fundamental abstract classes that define the common structure and behavior for all Linode API resources. It covers object instantiation, attribute management, and basic serialization/deserialization, providing a foundational layer for interacting with the Linode API. + +### Base API Object +The Base API Object component provides fundamental functionalities for interacting with the Linode API. It handles lazy loading of object properties, saving mutable values to the server via PUT requests, deleting objects, and invalidating cached data to force re-fetching from the server. It also manages relationships with other API objects. + + +**Related Classes/Methods**: + +- `linode_api4.objects.base.Base` (147:506) + + +### Mapped Object Utility +The Mapped Object Utility provides a way to convert dictionaries into objects where dictionary keys can be accessed as object attributes using dot notation. It also handles recursive conversion of nested dictionaries and lists of dictionaries into MappedObject instances, and provides serialization capabilities for these objects. + + +**Related Classes/Methods**: + +- `linode_api4.objects.base.MappedObject` (73:144) + + +### JSON Serialization +The JSON Serialization component is responsible for converting Python objects to and from JSON format. It provides methods for unwrapping types, parsing attributes from JSON, and serializing objects into a dictionary representation suitable for JSON output. + + +**Related Classes/Methods**: + +- `linode_api4.objects.serializable.JSONObject` (43:258) +- `linode_api4.objects.serializable.JSONFilterableMetaclass` (26:39) + + +### Request Body Flattening +This utility function recursively flattens data structures (dictionaries and lists) for use in API request bodies. It ensures that nested objects, including Base API Objects and Mapped Objects, are correctly serialized into their appropriate ID or dictionary representations before being sent in a request. + + +**Related Classes/Methods**: + +- `linode_api4.objects.base._flatten_request_body_recursive` (509:535) + + +### Derived Base Object +The Derived Base Object serves as an abstract base class for API resources that inherit common functionalities from the Base API Object, providing a foundation for more specialized API entities. + + +**Related Classes/Methods**: + +- `linode_api4.objects.dbase.DerivedBase` (4:27) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Linode API Client.md b/.codeboarding/Linode API Client.md new file mode 100644 index 00000000..802aa584 --- /dev/null +++ b/.codeboarding/Linode API Client.md @@ -0,0 +1,130 @@ +```mermaid +graph LR + LinodeClient["LinodeClient"] + API_Groups["API Groups"] + Retry_Mechanism["Retry Mechanism"] + Error_Handling["Error Handling"] + Pagination["Pagination"] + API_Objects["API Objects"] + LinodeClient -- "initializes" --> API_Groups + LinodeClient -- "configures" --> Retry_Mechanism + LinodeClient -- "handles errors via" --> Error_Handling + LinodeClient -- "manages" --> Pagination + API_Groups -- "interacts with" --> API_Objects + Pagination -- "requests data from" --> LinodeClient + API_Groups -- "returns" --> API_Objects + LinodeClient -- "returns" --> API_Objects + Error_Handling -- "used by" --> LinodeClient + Error_Handling -- "used by" --> API_Groups +``` +[![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 Linode API Client subsystem provides a comprehensive interface for programmatic interaction with the Linode API. It centralizes authentication, request execution, and response handling through the `LinodeClient`, which orchestrates API calls and manages various API resource groups. The system incorporates robust error handling, a retry mechanism for transient failures, and efficient pagination for large datasets, ensuring reliable and structured access to Linode resources represented as `API Objects`. + +### LinodeClient +The central component for interacting with the Linode API, handling authentication, request execution, response handling, and retry mechanisms. It orchestrates all API interactions and initializes various API group objects. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.linode_client.LinodeClient` (54:488) +- `python-linode-api.linode_api4.linode_client.LinodeClient:_api_call` (250:302) +- `python-linode-api.linode_api4.linode_client.LinodeClient:_get_objects` (304:333) +- `python-linode-api.linode_api4.linode_client.LinodeClient:get` (335:336) +- `python-linode-api.linode_api4.linode_client.LinodeClient:post` (338:339) +- `python-linode-api.linode_api4.linode_client.LinodeClient:put` (341:342) +- `python-linode-api.linode_api4.linode_client.LinodeClient:delete` (344:345) + + +### API Groups +A collection of specialized classes, each dedicated to managing interactions with a specific set of Linode API resources (e.g., Linodes, Accounts, Domains). These groups are initialized by the `LinodeClient` and provide a structured interface for performing operations on their respective resources. They inherit from `linode_api4.groups.group.Group`. + + +**Related Classes/Methods**: + +- `linode_api4.groups.group.Group` (9:11) +- `linode_api4.groups.linode.LinodeGroup` (29:451) +- `linode_api4.groups.profile.ProfileGroup` (18:345) +- `linode_api4.groups.account.AccountGroup` (24:512) +- `linode_api4.groups.networking.NetworkingGroup` (16:396) +- `linode_api4.groups.support.SupportGroup` (17:105) +- `linode_api4.groups.longview.LongviewGroup` (10:107) +- `linode_api4.groups.object_storage.ObjectStorageGroup` (29:535) +- `linode_api4.groups.lke.LKEGroup` (17:207) +- `linode_api4.groups.database.DatabaseGroup` (20:377) +- `linode_api4.groups.nodebalancer.NodeBalancerGroup` (6:70) +- `linode_api4.groups.domain.DomainGroup` (6:61) +- `linode_api4.groups.tag.TagGroup` (6:116) +- `linode_api4.groups.volume.VolumeGroup` (7:95) +- `linode_api4.groups.region.RegionGroup` (6:45) +- `linode_api4.groups.image.ImageGroup` (12:173) +- `linode_api4.groups.vpc.VPCGroup` (9:104) +- `linode_api4.groups.polling.PollingGroup` (9:91) +- `linode_api4.groups.beta.BetaProgramGroup` (5:24) +- `linode_api4.groups.placement.PlacementAPIGroup` (13:76) +- `linode_api4.groups.monitor.MonitorGroup` (19:153) + + +### Retry Mechanism +Implements a linear backoff strategy for retrying failed HTTP requests to the Linode API. It is configured within the `LinodeClient` to handle transient network issues or rate limiting by retrying requests based on specified HTTP status codes and intervals. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.linode_client.LinearRetry` (44:51) + + +### Error Handling +Provides classes for representing and handling various types of errors encountered during API interactions. `ApiError` specifically captures errors returned by the Linode API, while `UnexpectedResponseError` deals with responses that do not conform to expected structures. + + +**Related Classes/Methods**: + +- `linode_api4.errors.ApiError` (11:100) +- `linode_api4.errors.ApiError.from_response` (37:100) +- `linode_api4.errors.UnexpectedResponseError` (103:149) + + +### Pagination +Manages the retrieval and iteration over paginated lists of resources from the Linode API. It allows treating paginated results as a single, continuous list, automatically fetching additional pages as needed. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.paginated_list.PaginatedList` (6:262) +- `python-linode-api.linode_api4.paginated_list.PaginatedList.make_paginated_list` (230:262) +- `python-linode-api.linode_api4.paginated_list.PaginatedList.make_list` (195:227) + + +### API Objects +Represents the various resources returned by the Linode API (e.g., Linode instances, Domains, Accounts). These objects are typically instantiated by the `LinodeClient` or API Group methods and provide attributes and methods for interacting with the specific resource. + + +**Related Classes/Methods**: + +- `linode_api4.objects.base.Base` (147:506) +- `linode_api4.objects.dbase.DerivedBase` (4:27) +- `linode_api4.objects.account.Account` (25:56) +- `linode_api4.objects.linode.Instance` (full file reference) +- `linode_api4.objects.domain.Domain` (34:160) +- `linode_api4.objects.image.Image` (33:89) +- `linode_api4.objects.lke.LKECluster` (267:639) +- `linode_api4.objects.longview.LongviewClient` (4:21) +- `linode_api4.objects.monitor.MonitorDashboard` (141:157) +- `linode_api4.objects.networking.Firewall` (198:307) +- `linode_api4.objects.nodebalancer.NodeBalancer` (232:357) +- `linode_api4.objects.object_storage.ObjectStorageBucket` (82:502) +- `linode_api4.objects.placement.PlacementGroup` (57:128) +- `linode_api4.objects.profile.Profile` (59:186) +- `linode_api4.objects.region.Region` (19:51) +- `linode_api4.objects.support.SupportTicket` (39:190) +- `linode_api4.objects.tag.Tag` (19:79) +- `linode_api4.objects.volume.Volume` (31:147) +- `linode_api4.objects.vpc.VPC` (44:116) + + + + +### [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 00000000..bdac5fc8 --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,186 @@ +```mermaid +graph LR + Linode_API_Client["Linode API Client"] + API_Resource_Group_Managers["API Resource Group Managers"] + Core_API_Data_Models["Core API Data Models"] + API_Resource_Data_Models["API Resource Data Models"] + API_Error_Handling["API Error Handling"] + API_Utilities["API Utilities"] + Linode_API_Client -- "orchestrates" --> API_Resource_Group_Managers + API_Resource_Group_Managers -- "uses" --> Linode_API_Client + Linode_API_Client -- "handles" --> API_Error_Handling + API_Error_Handling -- "reports_to" --> Linode_API_Client + Linode_API_Client -- "leverages" --> API_Utilities + API_Resource_Group_Managers -- "manages" --> API_Resource_Data_Models + API_Resource_Group_Managers -- "leverages" --> API_Utilities + Core_API_Data_Models -- "defines_base_for" --> API_Resource_Data_Models + API_Resource_Data_Models -- "extends" --> Core_API_Data_Models + API_Resource_Data_Models -- "interacts_via" --> Linode_API_Client + API_Resource_Data_Models -- "affected_by" --> API_Error_Handling + API_Utilities -- "supports" --> Core_API_Data_Models + click Linode_API_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-linode-api/Linode API Client.md" "Details" + click API_Resource_Group_Managers href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-linode-api/API Resource Group Managers.md" "Details" + click Core_API_Data_Models href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-linode-api/Core API Data Models.md" "Details" + click API_Resource_Data_Models href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-linode-api/API Resource Data Models.md" "Details" + click API_Error_Handling href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-linode-api/API Error Handling.md" "Details" + click API_Utilities href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-linode-api/API Utilities.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 `python-linode-api` project provides a comprehensive Python client for interacting with the Linode API. Its main flow involves a central API client that orchestrates requests, which are then managed by specialized resource group managers. These managers operate on structured API data models, with core models defining the base structure and specific models representing various Linode resources. The system also incorporates robust error handling and a suite of utility functions to support API interactions, including pagination, filtering, and authentication. + +### Linode API Client +The primary client for interacting with the Linode API, responsible for authentication, request execution, response handling, and retry mechanisms. It orchestrates all API interactions. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.linode_client.LinodeClient` (54:488) +- `python-linode-api.linode_api4.linode_client.LinearRetry` (44:51) +- `python-linode-api.linode_api4.linode_client.LinodeClient:_api_call` (250:302) +- `python-linode-api.linode_api4.linode_client.LinodeClient:_get_objects` (304:333) +- `python-linode-api.linode_api4.linode_client.LinodeClient:get` (335:336) +- `python-linode-api.linode_api4.linode_client.LinodeClient:post` (338:339) +- `python-linode-api.linode_api4.linode_client.LinodeClient:put` (341:342) +- `python-linode-api.linode_api4.linode_client.LinodeClient:delete` (344:345) + + +### API Resource Group Managers +A collection of specialized classes, each providing high-level methods for managing a specific category of Linode API resources (e.g., Linodes, Accounts, Databases, Domains). They abstract direct API calls for resource-specific operations. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.groups.linode.LinodeGroup` (29:451) +- `python-linode-api.linode_api4.groups.profile.ProfileGroup` (18:345) +- `python-linode-api.linode_api4.groups.account.AccountGroup` (24:512) +- `python-linode-api.linode_api4.groups.networking.NetworkingGroup` (16:396) +- `python-linode-api.linode_api4.groups.support.SupportGroup` (17:105) +- `python-linode-api.linode_api4.groups.longview.LongviewGroup` (10:107) +- `python-linode-api.linode_api4.groups.object_storage.ObjectStorageGroup` (29:535) +- `python-linode-api.linode_api4.groups.lke.LKEGroup` (17:207) +- `python-linode-api.linode_api4.groups.database.DatabaseGroup` (20:377) +- `python-linode-api.linode_api4.groups.nodebalancer.NodeBalancerGroup` (6:70) +- `python-linode-api.linode_api4.groups.domain.DomainGroup` (6:61) +- `python-linode-api.linode_api4.groups.tag.TagGroup` (6:116) +- `python-linode-api.linode_api4.groups.volume.VolumeGroup` (7:95) +- `python-linode-api.linode_api4.groups.region.RegionGroup` (6:45) +- `python-linode-api.linode_api4.groups.image.ImageGroup` (12:173) +- `python-linode-api.linode_api4.groups.vpc.VPCGroup` (9:104) +- `python-linode-api.linode_api4.groups.polling.PollingGroup` (9:91) +- `python-linode-api.linode_api4.groups.beta.BetaProgramGroup` (5:24) +- `python-linode-api.linode_api4.groups.placement.PlacementAPIGroup` (13:76) +- `python-linode-api.linode_api4.groups.monitor.MonitorGroup` (19:153) +- `python-linode-api.linode_api4.groups.lke_tier.LKETierGroup` (5:40) + + +### Core API Data Models +Fundamental abstract classes that define the common structure and behavior for all Linode API resources, handling object instantiation, attribute management, and basic serialization/deserialization. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.objects.base.Base` (147:506) +- `python-linode-api.linode_api4.objects.base.MappedObject` (73:144) +- `python-linode-api.linode_api4.objects.serializable.JSONObject` (43:258) +- `python-linode-api.linode_api4.objects.serializable.JSONFilterableMetaclass` (26:39) +- `python-linode-api.linode_api4.objects.dbase.DerivedBase` (4:27) +- `python-linode-api.linode_api4.objects.base._flatten_request_body_recursive` (509:535) + + +### API Resource Data Models +Concrete data models representing various Linode API resources such as Linode instances, databases, object storage, networking components, LKE clusters, NodeBalancers, account details, user profiles, domains, volumes, images, tags, support tickets, placement groups, and regions. These models extend the `Core API Data Models` to provide resource-specific attributes and methods. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.objects.linode.Instance` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Backup` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Disk` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Config` (full file reference) +- `python-linode-api.linode_api4.objects.linode.NetworkInterface` (full file reference) +- `python-linode-api.linode_api4.objects.linode.StackScript` (full file reference) +- `python-linode-api.linode_api4.objects.linode.Type` (full file reference) +- `linode_api4.objects.linode.UserDefinedField` (full file reference) +- `python-linode-api.linode_api4.objects.database.DatabaseType` (15:44) +- `python-linode-api.linode_api4.objects.database.DatabaseEngine` (47:74) +- `python-linode-api.linode_api4.objects.database.MySQLDatabase` (274:436) +- `python-linode-api.linode_api4.objects.database.PostgreSQLDatabase` (439:603) +- `python-linode-api.linode_api4.objects.database.Database` (612:670) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageBucket` (82:502) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageKeys` (561:578) +- `python-linode-api.linode_api4.objects.object_storage.ObjectStorageQuota` (581:616) +- `python-linode-api.linode_api4.objects.networking.Firewall` (198:307) +- `python-linode-api.linode_api4.objects.networking.IPAddress` (60:127) +- `linode_api4.objects.networking.IPv6Range` (26:45) +- `python-linode-api.linode_api4.objects.networking.FirewallDevice` (179:195) +- `python-linode-api.linode_api4.objects.lke.LKECluster` (267:639) +- `python-linode-api.linode_api4.objects.lke.LKENodePool` (173:264) +- `python-linode-api.linode_api4.objects.lke.LKENodePoolNode` (147:170) +- `python-linode-api.linode_api4.objects.nodebalancer.NodeBalancer` (232:357) +- `python-linode-api.linode_api4.objects.nodebalancer.NodeBalancerConfig` (75:229) +- `python-linode-api.linode_api4.objects.nodebalancer.NodeBalancerNode` (30:72) +- `python-linode-api.linode_api4.objects.account.Account` (25:56) +- `python-linode-api.linode_api4.objects.account.AccountSettings` (183:201) +- `python-linode-api.linode_api4.objects.account.ChildAccount` (59:89) +- `python-linode-api.linode_api4.objects.account.Event` (204:331) +- `python-linode-api.linode_api4.objects.account.InvoiceItem` (334:366) +- `python-linode-api.linode_api4.objects.account.OAuthClient` (390:488) +- `python-linode-api.linode_api4.objects.account.PaymentMethod` (130:162) +- `python-linode-api.linode_api4.objects.account.ServiceTransfer` (92:127) +- `python-linode-api.linode_api4.objects.account.User` (507:555) +- `python-linode-api.linode_api4.objects.account.UserGrants` (619:703) +- `linode_api4.objects.account.Grant` (577:616) +- `python-linode-api.linode_api4.objects.profile.Profile` (59:186) +- `python-linode-api.linode_api4.objects.profile.PersonalAccessToken` (25:41) +- `python-linode-api.linode_api4.objects.profile.SSHKey` (189:203) +- `python-linode-api.linode_api4.objects.profile.WhitelistEntry` (44:56) +- `python-linode-api.linode_api4.objects.domain.Domain` (34:160) +- `python-linode-api.linode_api4.objects.domain.DomainRecord` (5:31) +- `python-linode-api.linode_api4.objects.volume.Volume` (31:147) +- `python-linode-api.linode_api4.objects.image.Image` (33:89) +- `python-linode-api.linode_api4.objects.tag.Tag` (19:79) +- `python-linode-api.linode_api4.objects.tag.TaggedObjectProxy` (82:132) +- `python-linode-api.linode_api4.objects.support.SupportTicket` (39:190) +- `python-linode-api.linode_api4.objects.support.TicketReply` (18:36) +- `python-linode-api.linode_api4.objects.placement.PlacementGroup` (57:128) +- `python-linode-api.linode_api4.objects.region.Region` (19:51) + + +### API Error Handling +Manages and represents various error types that can be returned by the Linode API, providing structured information for error diagnosis and handling. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.errors.ApiError` (11:100) +- `python-linode-api.linode_api4.errors.UnexpectedResponseError` (103:149) +- `python-linode-api.linode_api4.polling.EventError` (9:26) + + +### API Utilities +A collection of utility classes and functions that support various aspects of API interaction, including event polling, OAuth login, pagination, filtering, and general data manipulation. + + +**Related Classes/Methods**: + +- `python-linode-api.linode_api4.polling.EventPoller` (97:250) +- `python-linode-api.linode_api4.polling.TimeoutContext` (29:94) +- `python-linode-api.linode_api4.login_client.LinodeLoginClient` (325:519) +- `python-linode-api.linode_api4.login_client.OAuthScopes` (22:322) +- `python-linode-api.linode_api4.paginated_list.PaginatedList` (6:262) +- `python-linode-api.linode_api4.objects.filtering.Filter` (122:173) +- `python-linode-api.linode_api4.objects.filtering.FilterableAttribute` (176:201) +- `linode_api4.objects.filtering.and_` (69:82) +- `linode_api4.objects.filtering.order_by` (85:102) +- `linode_api4.objects.filtering.limit` (105:119) +- `python-linode-api.linode_api4.util:drop_null_keys` (8:29) +- `linode_api4.common.load_and_validate_keys` (16:62) +- `linode_api4.objects.linode._expand_placement_group_assignment` (full file reference) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file