docs: updates readme with additional usage information (#131)

README.md

@@ -12,15 +12,36 @@ pip install posit-sdk
 
 ## Usage
 
+Establish server information and credentials using the following environment variables or when initializing a client. Then checkout some [examples](./examples/0001-overview.qmd) to get started.
+
+> [!CAUTION]
+> It is important to keep your API key safe and secure. Your API key grants access to your account and allows you to make authenticated requests to the Posit API. Treat your API key like a password and avoid sharing it with others. If you suspect that your API key has been compromised, regenerate a new one immediately to maintain the security of your account.
+
+### Option 1 (Preferred)
+
+```shell
+export CONNECT_API_KEY="my-secret-api-key"
+export CONNECT_SERVER="https://example.com/"
+```
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    print(client)
+```
+
+### Option 2
+
 ```python
 from posit.connect import Client
 
-# If CONNECT_API_KEY and CONNECT_SERVER are set in your environment,
-# they will be picked up, or you can pass them as arguments
-con = Client()
-con.users.find()
+with Client(api_key="my-secret-api-key", url="https://example.com") as client:
+    print(client)
 ```
 
+
+
 ## Contributing
 
 We welcome contributions to the Posit SDK for Python! If you would like to contribute, see the [CONTRIBUTING](CONTRIBUTING.md) guide for instructions.

examples/0001-overview.qmd

@@ -0,0 +1,47 @@
+# Overview
+
+This file provides a collection of short examples to help users get started.
+
+The examples cover various aspects, including authentication, data retrieval, and data manipulation.
+
+## Example - Print information for each user where `user_role='publisher'`
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    for user in client.users.find(user_role='publisher'):
+        print(user)
+```
+
+## Example - Print information for a single user where `prefix='b'`
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    user = client.users.find_one(prefix='b')
+    print(user)
+```
+
+## Example - Print the title for each content item that I own.
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    guid = client.me.guid
+    for item in client.content.find(owner_guid=guid)
+        print(item.title)
+```
+
+## Example - Update the title for a content item.
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    guid = ... # the guid for a content item
+    item = client.content.get(guid)
+    item.update(title='New Title')
+```