Merge branch 'main' into zhiwei/makefile-standard-unit-test-fix

README.md

@@ -4,7 +4,7 @@ This package allows Python projects to easily interact with the [Linode Metadata
 
 ## Getting Started
 
-### Prerequisites 
+### Prerequisites
 
 - Python >= 3.8
 - A running [Linode Instance](https://www.linode.com/docs/api/linode-instances/)
@@ -16,24 +16,24 @@ pip install linode_metadata
 ```
 
 ### Building from Source
+
 To build and install this package:
 
 - Clone this repository
 - `make install`
 
-### Basic Example
+## Examples
 
-The following sample shows a simple Python project that initializes a new metadata client and retrieves various information
-about the current Linode.
+The following code snippets show multiple different ways to use the metadata
+client and retrieves various metadata of the current Linode.
 
+### Basic Usage
 
 ```python
 from linode_metadata import MetadataClient
 
 client = MetadataClient()
 
-# All of these responses are handled as DataClasses,
-# allowing IDEs to properly use completions.
 instance_info = client.get_instance()
 network_info = client.get_network()
 ssh_info = client.get_ssh_keys()
@@ -45,15 +45,49 @@ print("SSH Keys:", "; ".join(ssh_info.users.root))
 print("User Data:", user_data)
 ```
 
+### Asynchronous I/O and Context Manager Support
+
+You can also use the context manager to ensure the HTTP client will be properly closed, and the
+`asyncio` enabled client is also available.
+
+```python
+import asyncio
+from linode_metadata import AsyncMetadataClient
+
+async def get_metadata():
+    with AsyncMetadataClient() as client:
+        instance_info = await client.get_instance()
+        print("Instance ID:", instance_info.id)
+
+asyncio.run(get_metadata())
+```
+
+### Watchers
+
+Watchers are useful for monitor changes in the metadata, e.g. newly added IP address to the Linode.
+
+```python
+import asyncio
+from linode_metadata import AsyncMetadataClient
+
+async def get_metadata():
+    async with AsyncMetadataClient() as client:
+        watcher = client.get_watcher()
+        async for new_network_info in watcher.watch_network():
+            print(new_network_info)
+
+asyncio.run(get_metadata())
+```
+
 ## Testing
 
-Before running tests on this project, please ensure you have a 
+Before running tests on this project, please ensure you have a
 [Linode Personal Access Token](https://www.linode.com/docs/products/tools/api/guides/manage-api-tokens/)
 exported under the `LINODE_TOKEN` environment variable.
 
 ### End-to-End Testing Using Ansible
 
-This project contains an Ansible playbook to automatically deploy the necessary infrastructure 
+This project contains an Ansible playbook to automatically deploy the necessary infrastructure
 and run end-to-end tests on it.
 
 To install the dependencies for this playbook, ensure you have Python 3 installed and run the following:
@@ -68,14 +102,14 @@ After all dependencies have been installed, you can run the end-to-end test suit
 make int-test
 ```
 
-If your local SSH public key is stored in a location other than `~/.ssh/id_rsa.pub`, 
+If your local SSH public key is stored in a location other than `~/.ssh/id_rsa.pub`,
 you may need to override the `TEST_PUBKEY` argument:
 
 ```bash
 make TEST_PUBKEY=/path/to/my/pubkey int-test
 ```
 
-**NOTE: To speed up subsequent test runs, the infrastructure provisioned for testing will persist after the test run is complete. 
+**NOTE: To speed up subsequent test runs, the infrastructure provisioned for testing will persist after the test run is complete.
 This infrastructure is safe to manually remove.**
 
 ### Manual End-to-End Testing

ansible.cfg

@@ -0,0 +1,2 @@
+[defaults]
+deprecation_warnings=False

linode_metadata/__init__.py

@@ -2,5 +2,6 @@
 Initializes objects for Metadata Client
 """
 
-from linode_metadata.metadata_client import MetadataAsyncClient, MetadataClient
+from linode_metadata.metadata_client import AsyncMetadataClient, MetadataClient
 from linode_metadata.objects import *
+from linode_metadata.watcher import AsyncMetadataWatcher, MetadataWatcher

linode_metadata/constants.py

@@ -0,0 +1,5 @@
+"""
+Constants values for the linode_metadata package.
+"""
+
+LOGGER_NAME = "linode_metadata"