atlascloudsdk 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. atlascloudsdk-0.1.1/ATLAS_SDK_GUIDE.md +13 -0
  2. atlascloudsdk-0.1.1/CHANGELOG.md +16 -0
  3. atlascloudsdk-0.1.1/LICENSE +21 -0
  4. atlascloudsdk-0.1.1/MANIFEST.in +7 -0
  5. atlascloudsdk-0.1.1/PKG-INFO +222 -0
  6. atlascloudsdk-0.1.1/README.md +190 -0
  7. atlascloudsdk-0.1.1/docs/examples.md +202 -0
  8. atlascloudsdk-0.1.1/docs/index.md +50 -0
  9. atlascloudsdk-0.1.1/docs/production-readiness.md +25 -0
  10. atlascloudsdk-0.1.1/docs/sdk-flow.md +587 -0
  11. atlascloudsdk-0.1.1/examples/__init__.py +1 -0
  12. atlascloudsdk-0.1.1/examples/auth.py +26 -0
  13. atlascloudsdk-0.1.1/examples/compute_units.py +53 -0
  14. atlascloudsdk-0.1.1/examples/instances.py +98 -0
  15. atlascloudsdk-0.1.1/examples/networks.py +66 -0
  16. atlascloudsdk-0.1.1/examples/projects.py +59 -0
  17. atlascloudsdk-0.1.1/examples/security_groups.py +108 -0
  18. atlascloudsdk-0.1.1/examples/ssh_keys.py +61 -0
  19. atlascloudsdk-0.1.1/examples/vdc.py +53 -0
  20. atlascloudsdk-0.1.1/mkdocs.yml +11 -0
  21. atlascloudsdk-0.1.1/pyproject.toml +68 -0
  22. atlascloudsdk-0.1.1/setup.cfg +4 -0
  23. atlascloudsdk-0.1.1/src/atlas/__init__.py +57 -0
  24. atlascloudsdk-0.1.1/src/atlas/_http/__init__.py +1 -0
  25. atlascloudsdk-0.1.1/src/atlas/_http/transport.py +352 -0
  26. atlascloudsdk-0.1.1/src/atlas/auth.py +245 -0
  27. atlascloudsdk-0.1.1/src/atlas/cli/__init__.py +1 -0
  28. atlascloudsdk-0.1.1/src/atlas/cli/commands/__init__.py +1 -0
  29. atlascloudsdk-0.1.1/src/atlas/cli/commands/auth.py +62 -0
  30. atlascloudsdk-0.1.1/src/atlas/cli/commands/gpu.py +1 -0
  31. atlascloudsdk-0.1.1/src/atlas/cli/commands/instances.py +188 -0
  32. atlascloudsdk-0.1.1/src/atlas/cli/commands/kubernetes.py +1 -0
  33. atlascloudsdk-0.1.1/src/atlas/cli/commands/network.py +41 -0
  34. atlascloudsdk-0.1.1/src/atlas/cli/commands/projects.py +53 -0
  35. atlascloudsdk-0.1.1/src/atlas/cli/commands/security_groups.py +177 -0
  36. atlascloudsdk-0.1.1/src/atlas/cli/commands/ssh.py +88 -0
  37. atlascloudsdk-0.1.1/src/atlas/cli/commands/vdc.py +37 -0
  38. atlascloudsdk-0.1.1/src/atlas/cli/context.py +23 -0
  39. atlascloudsdk-0.1.1/src/atlas/cli/main.py +26 -0
  40. atlascloudsdk-0.1.1/src/atlas/cli/output.py +6 -0
  41. atlascloudsdk-0.1.1/src/atlas/cli/token_store.py +72 -0
  42. atlascloudsdk-0.1.1/src/atlas/client.py +216 -0
  43. atlascloudsdk-0.1.1/src/atlas/config.py +1 -0
  44. atlascloudsdk-0.1.1/src/atlas/connection.py +85 -0
  45. atlascloudsdk-0.1.1/src/atlas/exceptions.py +139 -0
  46. atlascloudsdk-0.1.1/src/atlas/models/__init__.py +1 -0
  47. atlascloudsdk-0.1.1/src/atlas/models/gpu.py +1 -0
  48. atlascloudsdk-0.1.1/src/atlas/models/kubernetes.py +1 -0
  49. atlascloudsdk-0.1.1/src/atlas/models/project.py +1 -0
  50. atlascloudsdk-0.1.1/src/atlas/pagination.py +1 -0
  51. atlascloudsdk-0.1.1/src/atlas/resources/__init__.py +5 -0
  52. atlascloudsdk-0.1.1/src/atlas/resources/base.py +25 -0
  53. atlascloudsdk-0.1.1/src/atlas/resources/compute.py +35 -0
  54. atlascloudsdk-0.1.1/src/atlas/resources/compute_units.py +27 -0
  55. atlascloudsdk-0.1.1/src/atlas/resources/gpu.py +1 -0
  56. atlascloudsdk-0.1.1/src/atlas/resources/instances.py +82 -0
  57. atlascloudsdk-0.1.1/src/atlas/resources/kubernetes.py +1 -0
  58. atlascloudsdk-0.1.1/src/atlas/resources/networks.py +69 -0
  59. atlascloudsdk-0.1.1/src/atlas/resources/projects.py +42 -0
  60. atlascloudsdk-0.1.1/src/atlas/resources/security_groups.py +115 -0
  61. atlascloudsdk-0.1.1/src/atlas/resources/ssh_keys.py +44 -0
  62. atlascloudsdk-0.1.1/src/atlas/resources/vdc.py +39 -0
  63. atlascloudsdk-0.1.1/src/atlas/version.py +3 -0
  64. atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/PKG-INFO +222 -0
  65. atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/SOURCES.txt +67 -0
  66. atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/dependency_links.txt +1 -0
  67. atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/entry_points.txt +2 -0
  68. atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/requires.txt +11 -0
  69. atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/top_level.txt +2 -0
@@ -0,0 +1,13 @@
1
+ # Atlas SDK documentation
2
+
3
+ The maintained documentation is published from the `docs/` directory.
4
+
5
+ - Start with [docs/index.md](docs/index.md) for the SDK overview.
6
+ - Read [docs/examples.md](docs/examples.md) for runnable examples.
7
+ - Read [docs/production-readiness.md](docs/production-readiness.md) for current limitations and release guidance.
8
+
9
+ Build the documentation locally with:
10
+
11
+ ```bash
12
+ mkdocs serve
13
+ ```
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ ## [0.1.1] - 2026-11-02
4
+
5
+ ### Added
6
+
7
+ - Established the Atlas SDK as the `atlascloudsdk` Python distribution, with
8
+ `from atlas import Connection` as the primary import.
9
+ - Documented authentication, resource discovery, and virtual machine
10
+ provisioning, with runnable examples and CLI guidance.
11
+
12
+ ### Changed
13
+
14
+ - Set the Atlas package version to `0.1.1` for the new project.
15
+ - Updated the public CLI command, package metadata, documentation, and
16
+ examples to use Atlas naming.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Atlas
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files, to deal in the Software
7
+ without restriction, including without limitation the rights to use, copy,
8
+ modify, merge, publish, distribute, sublicense, and/or sell copies of the
9
+ Software, and to permit persons to whom the Software is furnished to do so,
10
+ subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,7 @@
1
+ include CHANGELOG.md
2
+ include LICENSE
3
+ include README.md
4
+ include ATLAS_SDK_GUIDE.md
5
+ include mkdocs.yml
6
+ recursive-include docs *.md
7
+ recursive-include examples *.py
@@ -0,0 +1,222 @@
1
+ Metadata-Version: 2.4
2
+ Name: atlascloudsdk
3
+ Version: 0.1.1
4
+ Summary: Python SDK for the Atlas API
5
+ Author: Atlas
6
+ License-Expression: MIT
7
+ Keywords: atlas,cloud,sdk,api
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: requests>=2.32.0
22
+ Requires-Dist: typer>=0.12.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest; extra == "dev"
25
+ Requires-Dist: pytest-cov; extra == "dev"
26
+ Requires-Dist: ruff; extra == "dev"
27
+ Requires-Dist: mypy; extra == "dev"
28
+ Requires-Dist: build; extra == "dev"
29
+ Requires-Dist: twine; extra == "dev"
30
+ Requires-Dist: mkdocs-material; extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ # Atlas Python SDK
34
+
35
+ Python SDK for managing Atlas resources through the Atlas API, including projects, networks, SSH keys, security groups, compute options, and virtual machines.
36
+
37
+ The SDK supports authenticated API connections, resource discovery, and virtual machine provisioning.
38
+
39
+ ## Installation
40
+
41
+ Install the Atlas Python SDK:
42
+ ```bash
43
+ pip install atlascloudsdk
44
+ ```
45
+
46
+ Use TestPyPI only when testing a pre-release build.
47
+
48
+ Python 3.10 or newer is required.
49
+
50
+ The current SDK version is `0.1.1`.
51
+
52
+ ## Create a Connection
53
+
54
+ Create one authenticated connection and reuse it for API calls.
55
+
56
+ ```python
57
+ from atlas import Connection
58
+
59
+ with Connection(
60
+ base_url="https://your-atlas-host",
61
+ username="your-username",
62
+ password="your-password",
63
+ ) as client:
64
+ projects = client.projects.list(
65
+ enterprise_ref_key="ENTERPRISE_REF_KEY",
66
+ )
67
+ print(projects)
68
+ ```
69
+
70
+ Replace the example URL and credentials with your Atlas environment details.
71
+
72
+ Applications that already have valid access and refresh tokens can initialize a connection without logging in again:
73
+
74
+ ```python
75
+ from atlas import Connection
76
+
77
+ client = Connection.from_tokens(
78
+ base_url="https://your-atlas-host",
79
+ access_token="ACCESS_TOKEN",
80
+ refresh_token="REFRESH_TOKEN",
81
+ )
82
+ ```
83
+
84
+ ## Discover Resources
85
+
86
+ Use the reference keys returned by each API response when requesting related resources. Replace the placeholder reference keys below with valid values from your environment.
87
+
88
+ ```python
89
+ from atlas import Connection
90
+
91
+ with Connection(
92
+ base_url="https://your-atlas-host",
93
+ username="your-username",
94
+ password="your-password",
95
+ ) as client:
96
+ projects = client.projects.list(
97
+ enterprise_ref_key="ENTERPRISE_REF_KEY",
98
+ )
99
+
100
+ networks = client.networks.list(
101
+ project_ref_key="PROJECT_REF_KEY",
102
+ )
103
+
104
+ ssh_keys = client.ssh_keys.list(
105
+ project_ref_key="PROJECT_REF_KEY",
106
+ )
107
+
108
+ security_groups = client.security_groups.list(
109
+ project_ref_key="PROJECT_REF_KEY",
110
+ )
111
+
112
+ operating_systems = (
113
+ client.compute_units.list_operating_systems()
114
+ )
115
+
116
+ versions = client.compute_units.list_versions(
117
+ os_ref_key="OS_REF_KEY",
118
+ )
119
+
120
+ flavours = client.compute_units.list_flavours(
121
+ version_ref_key="VERSION_REF_KEY",
122
+ )
123
+
124
+ print("Projects:", projects)
125
+ print("Networks:", networks)
126
+ print("SSH keys:", ssh_keys)
127
+ print("Security groups:", security_groups)
128
+ print("Operating systems:", operating_systems)
129
+ print("Versions:", versions)
130
+ print("Flavours:", flavours)
131
+ ```
132
+
133
+ The API responses contain resource information, including reference keys where provided. Use the appropriate `ref_key` for subsequent operations. The SDK does not automatically select resources for you.
134
+
135
+ ## Provision a Virtual Machine
136
+
137
+ To create a virtual machine, provide valid project, SSH key, network, security group, and compute flavour reference keys, along with the other required provisioning parameters.
138
+
139
+ ```python
140
+ from atlas import Connection
141
+
142
+ with Connection(
143
+ base_url="https://your-atlas-host",
144
+ username="your-username",
145
+ password="your-password",
146
+ ) as client:
147
+ machine_name = "training-vm"
148
+
149
+ # Confirm the return semantics of this method in your SDK version.
150
+ is_name_available = client.instances.validate_machine_name(
151
+ project_ref_key="PROJECT_REF_KEY",
152
+ machine_name=machine_name,
153
+ )
154
+
155
+ if not is_name_available:
156
+ raise ValueError(
157
+ f"Machine name is already in use: {machine_name}"
158
+ )
159
+
160
+ payload = {
161
+ "project_ref_key": "PROJECT_REF_KEY",
162
+ "secret_ref_key": "SSH_SECRET_REF_KEY",
163
+ "network_ref_key": "NETWORK_REF_KEY",
164
+ "security_ref_key": "SECURITY_GROUP_REF_KEY",
165
+ "compute_ref_key": "FLAVOUR_REF_KEY",
166
+ "is_public_ip": False,
167
+ "bandwidth": 0,
168
+ "machine_name": machine_name,
169
+ "additional_storage": {"name": "", "size": 0},
170
+ "root_disk": 15,
171
+ "ai_services": [],
172
+ "platform_services": [],
173
+ "addons": [],
174
+ "license": {"name": "", "type": 0},
175
+ "time": 31,
176
+ "custom_flavour": "",
177
+ }
178
+
179
+ result = client.instances.create_vm(payload)
180
+ print(result)
181
+ ```
182
+
183
+ Replace all placeholder reference keys with valid values returned by the relevant APIs. Configure the disk size, billing duration, networking, and optional services according to your requirements.
184
+
185
+ **Note:** Provisioning is asynchronous. A successful response may indicate that the request was accepted, but it does not necessarily mean the virtual machine is ready. Use the instance list or get operations to inspect the result.
186
+
187
+ ## Error Handling
188
+
189
+ The SDK provides exceptions for handling API failures. The following example illustrates the pattern; use only exception classes available in your installed SDK version.
190
+
191
+ ```python
192
+ from atlas.exceptions import (
193
+ AtlasError,
194
+ AuthenticationError,
195
+ NotFoundError,
196
+ ValidationError,
197
+ )
198
+
199
+ try:
200
+ # Call an SDK resource method here.
201
+ pass
202
+
203
+ except AuthenticationError:
204
+ print("Authentication failed. Check your credentials.")
205
+
206
+ except ValidationError as error:
207
+ print("Validation failed:", error.details)
208
+
209
+ except NotFoundError:
210
+ print("Resource was not found.")
211
+
212
+ except AtlasError as error:
213
+ print("Status code:", error.status_code)
214
+ print("Details:", error.details)
215
+ ```
216
+
217
+ ## Security
218
+
219
+ - Never commit passwords, access tokens, refresh tokens, private keys, or API secrets to source control.
220
+ - Use HTTPS for production API communication.
221
+ - Store credentials in environment variables or a secure secrets manager.
222
+ - Keep downloaded SSH private keys secure and never print or log them.
@@ -0,0 +1,190 @@
1
+ # Atlas Python SDK
2
+
3
+ Python SDK for managing Atlas resources through the Atlas API, including projects, networks, SSH keys, security groups, compute options, and virtual machines.
4
+
5
+ The SDK supports authenticated API connections, resource discovery, and virtual machine provisioning.
6
+
7
+ ## Installation
8
+
9
+ Install the Atlas Python SDK:
10
+ ```bash
11
+ pip install atlascloudsdk
12
+ ```
13
+
14
+ Use TestPyPI only when testing a pre-release build.
15
+
16
+ Python 3.10 or newer is required.
17
+
18
+ The current SDK version is `0.1.1`.
19
+
20
+ ## Create a Connection
21
+
22
+ Create one authenticated connection and reuse it for API calls.
23
+
24
+ ```python
25
+ from atlas import Connection
26
+
27
+ with Connection(
28
+ base_url="https://your-atlas-host",
29
+ username="your-username",
30
+ password="your-password",
31
+ ) as client:
32
+ projects = client.projects.list(
33
+ enterprise_ref_key="ENTERPRISE_REF_KEY",
34
+ )
35
+ print(projects)
36
+ ```
37
+
38
+ Replace the example URL and credentials with your Atlas environment details.
39
+
40
+ Applications that already have valid access and refresh tokens can initialize a connection without logging in again:
41
+
42
+ ```python
43
+ from atlas import Connection
44
+
45
+ client = Connection.from_tokens(
46
+ base_url="https://your-atlas-host",
47
+ access_token="ACCESS_TOKEN",
48
+ refresh_token="REFRESH_TOKEN",
49
+ )
50
+ ```
51
+
52
+ ## Discover Resources
53
+
54
+ Use the reference keys returned by each API response when requesting related resources. Replace the placeholder reference keys below with valid values from your environment.
55
+
56
+ ```python
57
+ from atlas import Connection
58
+
59
+ with Connection(
60
+ base_url="https://your-atlas-host",
61
+ username="your-username",
62
+ password="your-password",
63
+ ) as client:
64
+ projects = client.projects.list(
65
+ enterprise_ref_key="ENTERPRISE_REF_KEY",
66
+ )
67
+
68
+ networks = client.networks.list(
69
+ project_ref_key="PROJECT_REF_KEY",
70
+ )
71
+
72
+ ssh_keys = client.ssh_keys.list(
73
+ project_ref_key="PROJECT_REF_KEY",
74
+ )
75
+
76
+ security_groups = client.security_groups.list(
77
+ project_ref_key="PROJECT_REF_KEY",
78
+ )
79
+
80
+ operating_systems = (
81
+ client.compute_units.list_operating_systems()
82
+ )
83
+
84
+ versions = client.compute_units.list_versions(
85
+ os_ref_key="OS_REF_KEY",
86
+ )
87
+
88
+ flavours = client.compute_units.list_flavours(
89
+ version_ref_key="VERSION_REF_KEY",
90
+ )
91
+
92
+ print("Projects:", projects)
93
+ print("Networks:", networks)
94
+ print("SSH keys:", ssh_keys)
95
+ print("Security groups:", security_groups)
96
+ print("Operating systems:", operating_systems)
97
+ print("Versions:", versions)
98
+ print("Flavours:", flavours)
99
+ ```
100
+
101
+ The API responses contain resource information, including reference keys where provided. Use the appropriate `ref_key` for subsequent operations. The SDK does not automatically select resources for you.
102
+
103
+ ## Provision a Virtual Machine
104
+
105
+ To create a virtual machine, provide valid project, SSH key, network, security group, and compute flavour reference keys, along with the other required provisioning parameters.
106
+
107
+ ```python
108
+ from atlas import Connection
109
+
110
+ with Connection(
111
+ base_url="https://your-atlas-host",
112
+ username="your-username",
113
+ password="your-password",
114
+ ) as client:
115
+ machine_name = "training-vm"
116
+
117
+ # Confirm the return semantics of this method in your SDK version.
118
+ is_name_available = client.instances.validate_machine_name(
119
+ project_ref_key="PROJECT_REF_KEY",
120
+ machine_name=machine_name,
121
+ )
122
+
123
+ if not is_name_available:
124
+ raise ValueError(
125
+ f"Machine name is already in use: {machine_name}"
126
+ )
127
+
128
+ payload = {
129
+ "project_ref_key": "PROJECT_REF_KEY",
130
+ "secret_ref_key": "SSH_SECRET_REF_KEY",
131
+ "network_ref_key": "NETWORK_REF_KEY",
132
+ "security_ref_key": "SECURITY_GROUP_REF_KEY",
133
+ "compute_ref_key": "FLAVOUR_REF_KEY",
134
+ "is_public_ip": False,
135
+ "bandwidth": 0,
136
+ "machine_name": machine_name,
137
+ "additional_storage": {"name": "", "size": 0},
138
+ "root_disk": 15,
139
+ "ai_services": [],
140
+ "platform_services": [],
141
+ "addons": [],
142
+ "license": {"name": "", "type": 0},
143
+ "time": 31,
144
+ "custom_flavour": "",
145
+ }
146
+
147
+ result = client.instances.create_vm(payload)
148
+ print(result)
149
+ ```
150
+
151
+ Replace all placeholder reference keys with valid values returned by the relevant APIs. Configure the disk size, billing duration, networking, and optional services according to your requirements.
152
+
153
+ **Note:** Provisioning is asynchronous. A successful response may indicate that the request was accepted, but it does not necessarily mean the virtual machine is ready. Use the instance list or get operations to inspect the result.
154
+
155
+ ## Error Handling
156
+
157
+ The SDK provides exceptions for handling API failures. The following example illustrates the pattern; use only exception classes available in your installed SDK version.
158
+
159
+ ```python
160
+ from atlas.exceptions import (
161
+ AtlasError,
162
+ AuthenticationError,
163
+ NotFoundError,
164
+ ValidationError,
165
+ )
166
+
167
+ try:
168
+ # Call an SDK resource method here.
169
+ pass
170
+
171
+ except AuthenticationError:
172
+ print("Authentication failed. Check your credentials.")
173
+
174
+ except ValidationError as error:
175
+ print("Validation failed:", error.details)
176
+
177
+ except NotFoundError:
178
+ print("Resource was not found.")
179
+
180
+ except AtlasError as error:
181
+ print("Status code:", error.status_code)
182
+ print("Details:", error.details)
183
+ ```
184
+
185
+ ## Security
186
+
187
+ - Never commit passwords, access tokens, refresh tokens, private keys, or API secrets to source control.
188
+ - Use HTTPS for production API communication.
189
+ - Store credentials in environment variables or a secure secrets manager.
190
+ - Keep downloaded SSH private keys secure and never print or log them.
@@ -0,0 +1,202 @@
1
+ # SDK examples
2
+
3
+ The `examples/` directory contains small scripts for the main Atlas SDK operations. Each script uses the same basic pattern:
4
+
5
+ 1. Fill in the empty configuration values at the top of the file.
6
+ 2. Run the first operation.
7
+ 3. Copy reference keys from the response into the next configuration value.
8
+ 4. Uncomment and run the next operation when it is ready.
9
+
10
+ Run the examples from the repository root:
11
+
12
+ ```bash
13
+ python examples/auth.py
14
+ python examples/vdc.py
15
+ ```
16
+
17
+ The examples use a `Connection` context manager, which closes the HTTP session automatically. The authentication example uses `AuthClient` directly.
18
+
19
+ ## Configuration
20
+
21
+ Every example keeps its configuration in simple variables near the top of the file:
22
+
23
+ ```python
24
+ BASE_URL = ""
25
+ USERNAME = ""
26
+ PASSWORD = ""
27
+ ```
28
+
29
+ Fill in only the values required by that example. Keep passwords, tokens, and private keys out of source control. Use HTTPS and keep TLS verification enabled in production.
30
+
31
+ ## Authentication
32
+
33
+ Run `examples/auth.py` to check that the credentials work:
34
+
35
+ ```bash
36
+ python examples/auth.py
37
+ ```
38
+
39
+ The script prints whether access and refresh tokens were received and shows the token expiry value. It never prints the token values themselves.
40
+
41
+ For normal SDK work, `Connection` performs authentication and makes the resource managers available on the client:
42
+
43
+ ```python
44
+ from atlas import Connection
45
+
46
+ with Connection(
47
+ base_url=BASE_URL,
48
+ username=USERNAME,
49
+ password=PASSWORD,
50
+ ) as client:
51
+ print(client.projects.list(enterprise_ref_key=ENTERPRISE_REF_KEY))
52
+ ```
53
+
54
+ ## Reference-key workflow
55
+
56
+ Most API calls need a reference key returned by an earlier call. The usual workflow is:
57
+
58
+ ```text
59
+ cluster -> VDC -> project -> network / SSH key / security group
60
+ -> operating system -> version -> flavour -> instance
61
+ ```
62
+
63
+ Do not guess or silently select a reference key. Read it from the API response and place it in the matching variable in the next example.
64
+
65
+ ## VDCs
66
+
67
+ `examples/vdc.py` provides three separate functions:
68
+
69
+ ```python
70
+ create_vdc()
71
+ get_vdc_details()
72
+ list_clusters()
73
+ ```
74
+
75
+ Start with `list_clusters()` when you need a valid `CLUSTER_REF_KEY`. Then use that key with `create_vdc()`. `get_vdc_details()` calls the VDC listing endpoint and prints the available VDC details.
76
+
77
+ The file runs `create_vdc()` by default. Uncomment the other function calls at the bottom when needed.
78
+
79
+ ## Projects
80
+
81
+ `examples/projects.py` provides:
82
+
83
+ ```python
84
+ create_project()
85
+ list_projects()
86
+ get_project()
87
+ ```
88
+
89
+ Project creation requires a `VDC_REF_KEY`. Listing requires an `ENTERPRISE_REF_KEY`, and getting one project requires its `PROJECT_REF_KEY`.
90
+
91
+ Run `list_projects()` to inspect the projects belonging to an enterprise. Copy a project reference key into `PROJECT_REF_KEY` before running `get_project()`.
92
+
93
+ ## Networks
94
+
95
+ `examples/networks.py` provides:
96
+
97
+ ```python
98
+ create_network()
99
+ list_networks()
100
+ delete_network()
101
+ ```
102
+
103
+ Network creation requires a project reference key and network settings:
104
+
105
+ - `NETWORK_NAME`: network name
106
+ - `SUBNET_NAME`: subnet name
107
+ - `SUBNET`: subnet value expected by the API
108
+ - `CIDR`: network CIDR
109
+ - `DNS`: a list of DNS servers
110
+
111
+ After creation, copy the network reference key into `NETWORK_REF_KEY`. Use it only when you are ready to call `delete_network()`, because deletion removes the selected network.
112
+
113
+ ## SSH keys
114
+
115
+ `examples/ssh_keys.py` provides:
116
+
117
+ ```python
118
+ create_ssh_key()
119
+ list_ssh_keys()
120
+ download_private_key()
121
+ ```
122
+
123
+ Create an SSH key with `PROJECT_REF_KEY` and `SECRET_NAME`. Use `list_ssh_keys()` to inspect the keys in the project. `download_private_key()` writes the private key to `PRIVATE_KEY_OUTPUT_PATH`.
124
+
125
+ Protect the downloaded private-key file. Do not print it, commit it, or send it through an unsafe channel.
126
+
127
+ ## Security groups and rules
128
+
129
+ `examples/security_groups.py` provides:
130
+
131
+ ```python
132
+ create_security_group()
133
+ list_security_groups()
134
+ create_security_group_rule()
135
+ list_security_group_rules()
136
+ delete_security_group_rule()
137
+ ```
138
+
139
+ The normal order is:
140
+
141
+ 1. Create a security group for a project.
142
+ 2. Copy its reference key into `SECURITY_GROUP_REF_KEY`.
143
+ 3. Create a rule by filling in the direction, type, destination, protocol, and optional port range.
144
+ 4. Copy the rule reference key into `SECURITY_GROUP_RULE_REF_KEY`.
145
+ 5. List or delete the rule as needed.
146
+
147
+ Deleting a rule is permanent for that rule, so check the reference key before running `delete_security_group_rule()`.
148
+
149
+ ## Compute units
150
+
151
+ `examples/compute_units.py` follows a dependent discovery sequence:
152
+
153
+ ```python
154
+ list_operating_systems(client)
155
+ list_versions(client, OS_REF_KEY)
156
+ list_flavours(client, VERSION_REF_KEY)
157
+ ```
158
+
159
+ The file opens one authenticated connection in `main()` and passes it to each function. Run the operating-system lookup first, copy an OS reference key into `OS_REF_KEY`, and uncomment `list_versions(client, OS_REF_KEY)`. Then copy a version reference key into `VERSION_REF_KEY` and uncomment `list_flavours(client, VERSION_REF_KEY)`.
160
+
161
+ The returned flavour reference key is used as `COMPUTE_REF_KEY` when creating an instance.
162
+
163
+ ## Instances
164
+
165
+ `examples/instances.py` provides:
166
+
167
+ ```python
168
+ validate_machine_name(client)
169
+ create_instance(client)
170
+ list_instances(client)
171
+ get_instance(client)
172
+ delete_instance(client)
173
+ ```
174
+
175
+ The instance example uses one connection in `main()`. Before creation, set these reference keys:
176
+
177
+ - `PROJECT_REF_KEY`
178
+ - `SSH_SECRET_REF_KEY`
179
+ - `NETWORK_REF_KEY`
180
+ - `SECURITY_GROUP_REF_KEY`
181
+ - `COMPUTE_REF_KEY`
182
+
183
+ The example first validates `MACHINE_NAME`. If the name is available, uncomment `create_instance(client)`. VM creation can be asynchronous, so a successful response means that the request was accepted; use `list_instances(client)` or `get_instance(client)` to inspect the result.
184
+
185
+ Copy the created instance reference key into `INSTANCE_REF_KEY` before using `get_instance(client)` or `delete_instance(client)`. Deleting an instance is destructive and should be performed only after checking the key.
186
+
187
+ ## Using one connection for several operations
188
+
189
+ When several operations need to run in one process, open one connection and pass it to the functions:
190
+
191
+ ```python
192
+ with Connection(
193
+ base_url=BASE_URL,
194
+ username=USERNAME,
195
+ password=PASSWORD,
196
+ ) as client:
197
+ list_operating_systems(client)
198
+ list_versions(client, OS_REF_KEY)
199
+ list_flavours(client, VERSION_REF_KEY)
200
+ ```
201
+
202
+ This avoids creating a new authenticated session for every operation. The compute-unit and instance examples already use this pattern.