jrxFive · ivanmilevtues · Jun 9, 2025
diff --git a/.codeboarding/API Request Layer.md b/.codeboarding/API Request Layer.md
diff --git a/.codeboarding/Cluster Management.md b/.codeboarding/Cluster Management.md
diff --git a/.codeboarding/Event Stream.md b/.codeboarding/Event Stream.md
@@ -0,0 +1,51 @@
+```mermaid
+graph LR
+    Event_API["Event API"]
+    Event_Stream_Handler["Event Stream Handler"]
+    API_Requester["API Requester"]
+    Event_API -- "provides" --> Event_Stream_Handler
+    Event_Stream_Handler -- "uses" --> API_Requester
+```
+[![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 involved in establishing and managing real-time event streams from the Nomad server. The `Event API` acts as the entry point, providing access to the `Event Stream Handler`. The `Event Stream Handler` is responsible for the actual streaming process, leveraging the `API Requester` for underlying HTTP communication with the Nomad server.
+
+### Event API
+This component serves as the primary interface for accessing Nomad event-related functionalities. It initializes and provides access to event streaming capabilities.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L12-L27" target="_blank" rel="noopener noreferrer">`nomad.api.event.Event` (12:27)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L26-L27" target="_blank" rel="noopener noreferrer">`nomad.api.event.Event:__init__` (26:27)</a>
+
+
+### Event Stream Handler
+This component is responsible for establishing and maintaining a continuous stream of events from the Nomad API. It handles the underlying network communication, processes incoming event data, and manages the stream lifecycle using a separate thread.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L31-L133" target="_blank" rel="noopener noreferrer">`nomad.api.event.stream` (31:133)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L40-L41" target="_blank" rel="noopener noreferrer">`nomad.api.event.stream:__init__` (40:41)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L43-L68" target="_blank" rel="noopener noreferrer">`nomad.api.event.stream:_get_stream` (43:68)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L70-L133" target="_blank" rel="noopener noreferrer">`nomad.api.event.stream:get_stream` (70:133)</a>
+
+
+### API Requester
+This foundational component provides the core functionality for making HTTP requests to the Nomad API. It manages connection parameters, authentication tokens, and handles various aspects of the request lifecycle, including error handling and response processing.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L10-L220" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester` (10:220)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L17-L43" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester:__init__` (17:43)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L103-L120" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester:request` (103:120)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L122-L220" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester:_request` (122:220)</a>
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)
diff --git a/.codeboarding/Exception Handling.md b/.codeboarding/Exception Handling.md
@@ -0,0 +1,70 @@
+```mermaid
+graph LR
+    Request_Handling["Request Handling"]
+    Scaling_Policy_Management["Scaling Policy Management"]
+    Search_Operations["Search Operations"]
+    Nomad_API_Exception_Handling["Nomad API Exception Handling"]
+    Scaling_Policy_Management -- "initiates API requests" --> Request_Handling
+    Scaling_Policy_Management -- "validates input and raises exceptions" --> Nomad_API_Exception_Handling
+    Search_Operations -- "initiates API requests" --> Request_Handling
+    Search_Operations -- "validates input and raises exceptions" --> Nomad_API_Exception_Handling
+    Request_Handling -- "propagates API errors as exceptions" --> Nomad_API_Exception_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 graph illustrates the core components of the Nomad API client library, focusing on how requests are handled, specific API functionalities are managed (scaling and search), and how errors are uniformly managed through a dedicated exception handling system. The Request Handling component is central to all API interactions, while Scaling Policy Management and Search Operations represent specific API domains. The Nomad API Exception Handling component provides a robust error reporting mechanism across the client library.
+
+### Request Handling
+This component is responsible for constructing and sending HTTP requests to the Nomad API. It handles URL and query string building, adds authentication tokens and user agents, processes HTTP responses, and raises specific Nomad API exceptions for different error codes.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L10-L220" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester` (10:220)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L122-L220" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester:_request` (122:220)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L77-L84" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester._url_builder` (77:84)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L86-L101" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester._query_string_builder` (86:101)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L103-L120" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester.request` (103:120)</a>
+
+
+### Scaling Policy Management
+This component provides an interface to interact with the Nomad API for managing scaling policies. It allows fetching scaling policies and handles invalid parameters specific to scaling policy requests.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/scaling.py#L8-L74" target="_blank" rel="noopener noreferrer">`nomad.api.scaling.Scaling` (8:74)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/scaling.py#L31-L59" target="_blank" rel="noopener noreferrer">`nomad.api.scaling.Scaling:get_scaling_policies` (31:59)</a>
+
+
+### Search Operations
+This component facilitates searching within the Nomad API, supporting both exact and fuzzy searches across various contexts like jobs, allocations, and nodes. It validates search parameters before making requests.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/search.py#L8-L98" target="_blank" rel="noopener noreferrer">`nomad.api.search.Search` (8:98)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/search.py#L33-L66" target="_blank" rel="noopener noreferrer">`nomad.api.search.Search:search` (33:66)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/search.py#L68-L98" target="_blank" rel="noopener noreferrer">`nomad.api.search.Search:fuzzy_search` (68:98)</a>
+
+
+### Nomad API Exception Handling
+This component defines a hierarchy of custom exceptions that are raised in response to various error conditions encountered during interactions with the Nomad API, such as bad requests, unauthorized access, not found URLs, and conflicts. It provides specific error information for granular error management and debugging.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L6-L16" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.BaseNomadException` (6:16)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L35-L36" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.InvalidParameters` (35:36)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L27-L28" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.BadRequestNomadException` (27:28)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L23-L24" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L19-L20" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.URLNotFoundNomadException` (19:20)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L31-L32" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.VariableConflict` (31:32)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/exceptions.py#L39-L40" target="_blank" rel="noopener noreferrer">`nomad.api.exceptions.TimeoutNomadException` (39:40)</a>
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)
diff --git a/.codeboarding/Nomad Client Core.md b/.codeboarding/Nomad Client Core.md
@@ -0,0 +1,62 @@
+```mermaid
+graph LR
+    Nomad_Client_Core["Nomad Client Core"]
+    Nomad_API_Endpoints["Nomad API Endpoints"]
+    Nomad_Client_Core -- "initializes and provides access to" --> Nomad_API_Endpoints
+```
+[![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 python-nomad library, focusing on the central `Nomad Client Core` which serves as the entry point for interacting with the Nomad cluster. It details how the client initializes connections and provides access to various `Nomad API Endpoints`, each responsible for managing specific Nomad resources. The primary flow involves the client initializing and then utilizing these API endpoint modules to perform operations on the Nomad cluster.
+
+### Nomad Client Core
+The primary entry point for the python-nomad library, responsible for initializing the connection to the Nomad cluster and providing access to all other API-specific client modules. It acts as the central interface for users to interact with the Nomad cluster.
+
+
+**Related Classes/Methods**:
+
+- `nomad.Nomad` (full file reference)
+- `nomad.Nomad:__init__` (30:60)
+- `nomad.Nomad.get_uri` (62:65)
+
+
+### Nomad API Endpoints
+This component encompasses a collection of modules, each dedicated to managing a specific resource or functionality within the Nomad API, such as ACLs, agents, allocations, jobs, and nodes. These modules are instantiated by the Nomad Client to facilitate interactions with the respective Nomad services, often inheriting from a common `Requester` base class for API communication.
+
+
+**Related Classes/Methods**:
+
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/acl.py#L6-L194" target="_blank" rel="noopener noreferrer">`nomad.api.acl.Acl` (6:194)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/agent.py#L6-L98" target="_blank" rel="noopener noreferrer">`nomad.api.agent.Agent` (6:98)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/allocation.py#L8-L73" target="_blank" rel="noopener noreferrer">`nomad.api.allocation.Allocation` (8:73)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/allocations.py#L8-L83" target="_blank" rel="noopener noreferrer">`nomad.api.allocations.Allocations` (8:83)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/client.py#L7-L32" target="_blank" rel="noopener noreferrer">`nomad.api.client.Client` (7:32)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/deployment.py#L8-L172" target="_blank" rel="noopener noreferrer">`nomad.api.deployment.Deployment` (8:172)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/deployments.py#L8-L78" target="_blank" rel="noopener noreferrer">`nomad.api.deployments.Deployments` (8:78)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/evaluation.py#L8-L74" target="_blank" rel="noopener noreferrer">`nomad.api.evaluation.Evaluation` (8:74)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/evaluations.py#L8-L75" target="_blank" rel="noopener noreferrer">`nomad.api.evaluations.Evaluations` (8:75)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/event.py#L12-L27" target="_blank" rel="noopener noreferrer">`nomad.api.event.Event` (12:27)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/job.py#L9-L363" target="_blank" rel="noopener noreferrer">`nomad.api.job.Job` (9:363)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/jobs.py#L9-L127" target="_blank" rel="noopener noreferrer">`nomad.api.jobs.Jobs` (9:127)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/metrics.py#L6-L42" target="_blank" rel="noopener noreferrer">`nomad.api.metrics.Metrics` (6:42)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/namespace.py#L8-L107" target="_blank" rel="noopener noreferrer">`nomad.api.namespace.Namespace` (8:107)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/namespaces.py#L8-L75" target="_blank" rel="noopener noreferrer">`nomad.api.namespaces.Namespaces` (8:75)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/node.py#L9-L193" target="_blank" rel="noopener noreferrer">`nomad.api.node.Node` (9:193)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/nodes.py#L10-L95" target="_blank" rel="noopener noreferrer">`nomad.api.nodes.Nodes` (10:95)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/operator.py#L6-L64" target="_blank" rel="noopener noreferrer">`nomad.api.operator.Operator` (6:64)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/regions.py#L8-L68" target="_blank" rel="noopener noreferrer">`nomad.api.regions.Regions` (8:68)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/scaling.py#L8-L74" target="_blank" rel="noopener noreferrer">`nomad.api.scaling.Scaling` (8:74)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/search.py#L8-L98" target="_blank" rel="noopener noreferrer">`nomad.api.search.Search` (8:98)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/sentinel.py#L6-L98" target="_blank" rel="noopener noreferrer">`nomad.api.sentinel.Sentinel` (6:98)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/status.py#L8-L27" target="_blank" rel="noopener noreferrer">`nomad.api.status.Status` (8:27)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/system.py#L6-L52" target="_blank" rel="noopener noreferrer">`nomad.api.system.System` (6:52)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/validate.py#L6-L44" target="_blank" rel="noopener noreferrer">`nomad.api.validate.Validate` (6:44)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/variable.py#L8-L111" target="_blank" rel="noopener noreferrer">`nomad.api.variable.Variable` (8:111)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/variables.py#L6-L66" target="_blank" rel="noopener noreferrer">`nomad.api.variables.Variables` (6:66)</a>
+- <a href="https://github.com/jrxFive/python-nomad/blob/master/nomad/api/base.py#L10-L220" target="_blank" rel="noopener noreferrer">`nomad.api.base.Requester` (10:220)</a>
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)