Update readmes

README.md

@@ -1,39 +1,120 @@
-# Ziti SDK for Python
+<a href="https://docs.openziti.io/">
+    <img src="./images/ziti-logo-dark.svg" alt="ziti logo" title="OpenZiti" align="right" height="60" />
+</a>
 
-## Installation
+# Python SDK for OpenZiti
+<p align="center">
+  <a href="https://openziti.discourse.group/">
+    <img src="https://img.shields.io/discourse/users?server=https%3A%2F%2Fopenziti.discourse.group" alt="Discourse">
+  </a>
+  <a href="https://github.com/openziti/ziti-sdk-py">
+    <img src="https://img.shields.io/github/stars/openziti/ziti-sdk-py" alt="GitHub Stars"
+  </a>
+  <a href="https://pypi.org/project/openziti/">
+    <img src="https://img.shields.io/pypi/dd/openziti" alt="Downloads">
+  </a>
+  <a href="https://opensource.org/licenses/Apache-2.0">
+    <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
+  </a>
+</p>
 
-Ziti SDK for Python is distributed via Python Package Index(PyPI)
+<p align="center">
+  <a href="#getting-started">Getting Started</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#support">Support</a> •
+  <a href="#contributing">Contributing</a> •
+  <a href="#license">License</a>
+</p>
 
-```shell
-pip install openziti
-```
+<img src="./images/Ziggy-Loves-Python.svg" align="right" alt="ziggy-loves-python" width="15%">
+
+The Python SDK for [OpenZiti](https://github.com/openziti/ziti) is a library that enables you to integrate zero trust network connectivity into your Python 
+applications, and establish secure connections with remote network resources over an OpenZiti network. The SDK also 
+simplifies the process of adding secure, zero-trust network connectivity built into your Python application. It's so 
+simple that it can be done in just two lines of code!
+
+OpenZiti is an open-source project that provides secure, zero-trust networking for applications running on any platform.
 
-## Usage
+More specifically, the SDK allows you to integrate zero trust at the application level. This means your data is never 
+exposed outside the application environment providing you with end-to-end encryption for ultimate security. See other 
+zero trust models [here](https://docs.openziti.io/docs/learn/core-concepts/zero-trust-models/overview).
+<p align="center">
+<img src="./images/ztaa-model-overview.png" alt="Zero-trust-application-access">
+</p>
 
-### Identity Enrollment
+## Getting Started
+If you don't already have an OpenZiti network running, you can follow our [express install guides](https://docs.openziti.io/docs/learn/quickstarts/network/) 
+to set up the network that fits your needs. Or, you can try [CloudZiti](https://netfoundry.io/pricing/) for free, check out more [here](https://docs.openziti.io/).
 
-Acquire [Ziti Enrollment Token](https://openziti.github.io/ziti/identities/overview.html)
+### Installing the SDK
+
+The Python SDK for OpenZiti is distributed via the Python Package Index (PyPI) and can be installed using 
+[`pip`](https://pypi.org/project/openziti/) package manager.
 
 ```shell
-python -m openziti enroll -j <JWT file> -i <ID JSON file>
+pip install openziti
 ```
 
-### Environment Variables
+### Using Ziti Python SDK
+With just two lines of code, you can turn your plain old web server into a secure, zero-trust embedded application. 
+Below is an example of just how simple it is to get started.
 
-- `ZITI_IDENTITIES` is a semi-colon-separated list of file paths to Ziti identity configuration JSON files.
-- You may increase the log level of the underlying C SDK by setting environment variable `ZITI_LOG=4` (`DEBUG`).
+Provide a hostname, and port for your application, a simple monkey patch, and you're ready to go. You don't even need to 
+know what a monkey patch is! However, if you're interested in what a monkey patch is, expand the block below.
+<details>
+   <summary>What is Monkey Patching?</summary>
 
-### Samples
+   > Monkey patching allows developers to modify functionality for code even when they may not have access to the 
+   > original source code. Because Python has a dynamic object model allowing developers to modify objects at runtime. 
+   > Monkey patching allows developers to point a function call to any function they want. We can even implement our 
+   > own function that doesn't exist in the source code.
+   > 
+   > The way this Python SDK uses monkey patching is to override existing functionality in socket handling by the 
+   > [socket module](https://docs.python.org/3/library/socket.html).
+   > 
+   > Taking a look at the code below, the key lines are the last two. You can see how, for each monkey patched function, 
+   > we're telling that function call on the `sock` object to be directed to the function held in `_patch_methods`. 
+   > Therefore, this SDK can be used on any application that doesn't manage its own sockets.
+   > ```python
+   > def __init__(self, **kwargs):
+   >     self.orig_socket = sock.socket
+   >     sock.socket = _patchedSocket(kwargs)
+   >     self.orig_methods = {m: sock.__dict__[m] for m, _ in
+   >                          _patch_methods.items()}
+   >     for m_name, _ in _patch_methods.items():
+   >         sock.__dict__[m_name] = _patch_methods[m_name]
+   > ```
 
-We several Python SDK sample programs for clients and servers in [sample/README.md](sample/README.md).
+   </details>
 
-## Getting Help
+```python
+cfg = dict(ztx=openziti.load('/path/to/identity.json'), service="name-of-ziti-service")
+openziti.monkeypatch(bindings={('127.0.0.1', 8000): cfg})
+```
+Or try our decorator pattern with a function annotation
+```python
+@openziti.zitify(bindings={('127.0.0.1', 18080): {'ztx': '/path/to/identity.json', 'service': 'name-of-ziti-service'}})
+def yourFunction():
+```
+## Examples
+Try it out yourself with one of our [examples](sample%2FREADME.md)
+* [Flazk](sample/flask-of-ziti)
+* [Echo Server](sample/ziti-echo-server)
+* [HTTP Server](sample/ziti-http-server)
+* [Ziti Requests](sample/ziti-requests)
+* [Ziti Socket](sample/ziti-socket)
+* [Ziti urllib3](sample/ziti-urllib3)
 
+## Support
+### Looking for Help?
 Please use these community resources for getting help. We use GitHub [issues](https://github.com/openziti/ziti-sdk-py/issues)
 for tracking bugs and feature requests and have limited bandwidth to address them.
 
-- Read the [docs](https://openziti.github.io/ziti/overview.html)
+- Read the [offical docs](https://docs.openziti.io/docs/learn/introduction/)
 - Join our [Developer Community](https://openziti.org)
 - Participate in discussion on [Discourse](https://openziti.discourse.group/)
-
-Copyright&copy; 2018-2022. NetFoundry, Inc.
+## Contributing
+Do you want to get your hands dirty and help make OpenZiti better? Contribute to the OpenZiti open-source project 
+through bug reports, bug fixes, documentation, etc. Check out our guide on contributing to our projects [here](https://docs.openziti.io/policies/CONTRIBUTING.html).
+## License
+[Apache 2.0](./LICENSE)

sample/README.md

@@ -1,58 +1,77 @@
-# OpenZiti Python SDK in Action
+# Python SDK for OpenZiti Examples
 
-## Sample Setup
+## Setup
 
-See [the main README](../README.md) for general setup and environment details.
+In order to begin using the examples, you'll need an OpenZiti network. If you don't already have one running, you can follow our [express install guides](https://docs.openziti.io/docs/learn/quickstarts/network/) 
+to set up the network that fits your needs. You could also use [ZEDS](https://zeds.openziti.org) (Ziti Edge Developer Sandbox) or, you can try cloud Ziti for free, check out more [here](https://docs.openziti.io/).
 
-- install Python requirements
+### Installing the SDK
 
+The Python SDK for OpenZiti is distributed via the Python Package Index (PyPI) and can be installed using 
+[`pip`](https://pypi.org/project/openziti/) package manager.
+
+```shell
+pip install openziti
+```
+
+### Install Python Requirements
+First, you'll need the dependent libraries used in the examples.
   ```bash
   cd ./sample
   pip install -r requirements
   ```
 
-- get yourself a Ziti identity from [ZEDS](https://zeds.openziti.org)
-
-  follow enrollment instructions from the site, or better yet enroll with openziti Python module
+### Get and Enroll an Identity
+You need an [identity](https://docs.openziti.io/docs/learn/core-concepts/identities/overview) to be used by the example 
+application. If using [ZEDS](https://zeds.openziti.org) you can grab one from there, otherwise you can find all the
+information you need for creating and enrolling an identity in the [doc here](https://docs.openziti.io/docs/learn/core-concepts/identities/overview#creating-an-identity).
 
+Alternatively, if you have an identity enrollment token (JWT file), you can perform the enrollment with the Python SDK.
   ```bash
-  python -m openziti enroll --jwt=<enrollment token file> --identity=<identity file>
+  python -m openziti enroll --jwt=</path/to/enrollment-token-file.jwt> --identity=</path/to/id.json>
   ```
 
-  the following instructions assume that Ziti identity is stored in `id.json` file
-
-- set `ZITI_IDENTITIES` environment variable to location of `id.json` file
-
+### Environment
+The `ZITI_IDENTITIES` environment variable can be used to store the paths to any identity files you have. If you have 
+more than one identity file, you can use the `;` operator as a delimiter to provide additional identities.
   ```bash
-  export ZITI_IDENTITIES=<path to id.json>
+  export ZITI_IDENTITIES=</path/to/id.json>
   ```
 
-## Run Samples
-
-All sample scripts use predefined services in [ZEDS](https://zeds.openziti.org)
-
-### `flask-of-ziti/helloFlazk.py`
-
-Shows the use of a decorator function to monkeypatch a Flask server.
-
-### `h-ziti-p.py`
-
-Shows the use of Ziti monkeypatching standard socket to intercept network connections
-and using Ziti overlay.
+There is an optional environment variable `ZITI_LOG` which, by default is set to `1`. This value can be adjusted to 
+output more or less log information. A `ZITI_LOG` level of `6` will output `TRACE` level logs.
 
-### `http-get.py`
+### Network
+Your network overlay needs to have a [Service](https://docs.openziti.io/docs/learn/core-concepts/services/overview), 
+and the proper [Service Configurations](https://docs.openziti.io/docs/learn/core-concepts/config-store/overview), the 
+documentation for which is linked.
 
-Monkeypatch `requests.get(url)` to fetch a Ziti service with HTTP.
+If you happen to be using [ZEDS](https://zeds.openziti.org) you are in luck, these examples will use default services 
+that are already implemented in the developer sandbox.
 
-### `ziti-echo-server.py`
+## Examples
+> **Note**
+> All but the Flazk example scripts use predefined services in [ZEDS](https://zeds.openziti.org) by default.
 
-Open a socket to listen on the overlay for a particular Ziti service and send all bytes received back to the sender.
+### [Flazk](flask-of-ziti) <img src="../images/python-flask.jpg" width="2%">
+An example showing the simplicity in integrating zero trust into a web server or API using Flask. This example also 
+shows how to use the decorator to apply the monkeypatch.
+`flask-of-ziti/helloFlazk.py`
 
-### `ziti-http-server.py`
+### [Ziti Echo Server](ziti-echo-server)
+An example showing how to open a socket to listen on the network overlay for a particular service and send all bytes 
+received back to the sender.
 
-Monkeypatch `http.server` to listen for requests on the overlay. Respond to clients with a simple JSON document.
+### [Ziti HTTP Server](ziti-http-server)
+An example showing how to monkeypatch `http.server` to listen for HTTP requests on the network overlay. When a request 
+is captured, a response with a simple JSON document is sent to clients.
 
-### `ziti-socket-sample.py`
+### [Ziti Requests](ziti-requests)
+An example showing the use of Ziti monkey patching a standard socket, via the requests module, to intercept network 
+connections using Ziti overlay.
 
-Shows the use of _raw_ Ziti socket.
+### [Ziti Socket](ziti-socket)
+An example showing the use of a _raw_ Ziti socket.
 
+### [Ziti urllib3](ziti-urllib3)
+An example showing how to monkeypatch `urllib3` to fetch a Ziti service using HTTP.

sample/flask-of-ziti/README.md

@@ -0,0 +1,36 @@
+# Hello Flazk <img align="right" src="../../images/python-flask-text.png" width="20%">
+This example shows the simplicity in integrating zero trust into a web server or API using Flask. This example also 
+shows how to use the decorator to apply the monkeypatch.
+
+This is a perfect example of application to application embedded zero trust. When used in conjunction with the 
+[Ziti urllib3](../ziti-urllib3) example, both ends of the network are fully app-embedded zero trust applications and therefore 
+offer complete encryption from app to app, no unencrypted data ever leaves the application environment.
+![ztaa-model-flazk.png](..%2F..%2Fimages%2Fztaa-model-flazk.png)
+
+## Setup :wrench:
+Refer to the [examples README](../README.md) for details on setting up your network, service, and obtaining an identity 
+file.
+
+### Install Python Requirements
+If you haven't already installed them, you'll need the dependent libraries used in the examples.
+  ```bash
+  pip install -r ../requirements
+  ```
+
+## Running the Example :arrow_forward:
+This example accepts two input arguments. 
+1. The identity file to be used by the SDK tunneler
+2. The service to bind to
+```shell
+python helloFlazk.py </path/to/id.json> <name-of-service>
+```
+
+## Testing the Example :clipboard:
+By default, the base url is mapped to our `hello_world()` function. So, if we hit that endpoint we will see the 
+response from the function which is simply `Have some ziti`. This could be tested with 
+1. The [Ziti urllib3](../ziti-urllib3) example
+2. The [Ziti Requests](../ziti-requests) example
+3. A curl command
+
+       curl <name-of-service>:<intercept-port>
+4. Or simply visiting the intercept address in a browser.