Improve Installation/Usage in README, update badges for uv

README.md

@@ -5,17 +5,20 @@
 </p>
 
 <p align="center">
-    <a href="https://github.com/devine-dl/pywidevine/actions/workflows/ci.yml">
+    <a href="https://github.com/devine-dl/pywidevine/blob/master/LICENSE">
-        <img src="https://github.com/devine-dl/pywidevine/actions/workflows/ci.yml/badge.svg" alt="Build status">
+        <img src="https://img.shields.io/:license-GPL%203.0-blue.svg" alt="License">
     </a>
     <a href="https://pypi.org/project/pywidevine">
         <img src="https://img.shields.io/badge/python-3.9%2B-informational" alt="Python version">
     </a>
+    <a href="https://github.com/astral-sh/uv">
+        <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Onyx-Nostalgia/uv/refs/heads/fix/logo-badge/assets/badge/v0.json" alt="Manager: uv">
+    </a>
     <a href="https://github.com/astral-sh/ruff">
         <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Linter: Ruff">
     </a>
-    <a href="https://python-poetry.org">
+    <a href="https://github.com/devine-dl/pywidevine/actions/workflows/ci.yml">
-        <img src="https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json" alt="Dependency management: Poetry">
+        <img src="https://github.com/devine-dl/pywidevine/actions/workflows/ci.yml/badge.svg" alt="Build status">
     </a>
 </p>
 
@@ -32,22 +35,31 @@
 
 ## Installation
 
-```shell
+### With pip
-$ pip install pywidevine
-```
 
-> **Note**
+> Since *pip* is pre-installed with Python, it is the most straight forward way to install pywidevine.
-If pip gives you a warning about a path not being in your PATH environment variable then promptly add that path then
-close all open command prompt/terminal windows, or `pywidevine` CLI won't work as it will not be found.
 
-Voilà 🎉 — You now have the `pywidevine` package installed!  
+Simply run `pip install pywidevine` and it will be ready to use from the CLI or within scripts in a minute.
-You can now import pywidevine in scripts ([see below](#usage)).  
+
-A command-line interface is also available, try `pywidevine --help`.
+### With uv
+
+> This is recommended for those who wish to install from the source code, are working on changes in the source code, or
+just simply prefer it's many handy features.
+
+Go to to the official website and [get uv installed](https://docs.astral.sh/uv/getting-started/installation/). Download
+or clone this repository, go inside it, and run `uv run pywidevine --version`. To run scripts, like a `license.py` that
+is importing pywidevine, do `uv run license.py`. Effectively, put `uv run` before calling whatever is using pywidevine.
+For other ways to run pywidevine with uv, see [Running commands](https://docs.astral.sh/uv/guides/projects/#running-commands).
 
 ## Usage
 
-The following is a minimal example of using pywidevine in a script to get a License for Bitmovin's
+There are two ways to use pywidevine, through scripts, or the CLI (command-line interface).
-Art of Motion Demo.
+Most people would be using it through scripts due to complexities working with license server APIs.
+
+### Scripts
+
+The following is a minimal example of using pywidevine in a script to get a License for Bitmovin's Art of Motion Demo.
+This demo can be found on [Bitmovin's DRM Stream Test demo page](https://bitmovin.com/demos/drm/).
 
 ```py
 from pywidevine.cdm import Cdm
@@ -56,50 +68,93 @@ from pywidevine.pssh import PSSH
 
 import requests
 
-# prepare pssh
+# prepare pssh (usually inside the MPD/M3U8, an API response, the player page, or inside the pssh mp4 box)
 pssh = PSSH("AAAAW3Bzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAADsIARIQ62dqu8s0Xpa"
             "7z2FmMPGj2hoNd2lkZXZpbmVfdGVzdCIQZmtqM2xqYVNkZmFsa3IzaioCSEQyAA==")
 
-# load device
+# load device from a WVD file (your provision)
 device = Device.load("C:/Path/To/A/Provision.wvd")
 
-# load cdm
+# load cdm (creating a CDM instance using that device)
 cdm = Cdm.from_device(device)
 
-# open cdm session
+# open cdm session (note that any one device should have a practical limit to amount of sessions open at any one time)
 session_id = cdm.open()
 
-# get license challenge
+# get license challenge (generate a license request message, signed using the device with the pssh)
 challenge = cdm.get_license_challenge(session_id, pssh)
 
-# send license challenge (assuming a generic license server SDK with no API front)
+# send license challenge to bitmovin's license server (which has no auth and asks simply for the license challenge as-is)
-licence = requests.post("https://...", data=challenge)
+# another license server may require authentication and ask for it as JSON or form data instead
+# you may also be required to use privacy mode, where you use their service certificate when creating the challenge
+licence = requests.post("https://cwip-shaka-proxy.appspot.com/no_auth", data=challenge)
 licence.raise_for_status()
 
-# parse license challenge
+# parse the license response message received from the license server API
 cdm.parse_license(session_id, licence.content)
 
 # print keys
 for key in cdm.get_keys(session_id):
     print(f"[{key.type}] {key.kid.hex}:{key.key.hex()}")
 
-# close session, disposes of session data
+# finished, close the session, disposing of all keys and other related data
 cdm.close(session_id)
 ```
 
-> **Note**
+There are other features not shown in this small example like:
-> There are various features not shown in this specific example like:
+
->
+- Privacy Mode
-> - Privacy Mode
+- Setting Service Certificates
-> - Setting Service Certificates
+- Remote CDMs and Serving
-> - Remote CDMs and Serving
+- Choosing a License Type
-> - Choosing a License Type to request
+- Creating WVD files
-> - Creating WVD files
+- and much more!
-> - and much more!
+
->
+> [!TIP]
-> Take a look at the methods available in the [Cdm class](/pywidevine/cdm.py) and their doc-strings for
+> For examples, take a look at the methods available in the [Cdm class](/pywidevine/cdm.py) and read their doc-strings
-> further information. For more examples see the [CLI functions](/pywidevine/main.py) which uses a lot
+> for further information.
-> of previously mentioned features.
+
+### Command-line Interface
+
+The CLI can be useful to do simple license calls, migrate WVD files, and test provisions.
+Take a look at `pywidevine --help` to see a list of commands available.
+
+```plain
+Usage: pywidevine [OPTIONS] COMMAND [ARGS]...
+
+  pywidevine—Python Widevine CDM implementation.
+
+Options:
+  -v, --version  Print version information.
+  -d, --debug    Enable DEBUG level logs.
+  --help         Show this message and exit.
+
+Commands:
+  create-device  Create a Widevine Device (.wvd) file from an RSA Private...
+  export-device  Export a Widevine Device (.wvd) file to an RSA Private...
+  license        Make a License Request for PSSH to SERVER using DEVICE.
+  migrate        Upgrade from earlier versions of the Widevine Device...
+  serve          Serve your local CDM and Widevine Devices Remotely.
+  test           Test the CDM code by getting Content Keys for Bitmovin's...
+```
+
+Every command has further help information, simply type `pywidevine <command> --help`.
+For example, `pywidevine test --help`:
+
+```plain
+Usage: pywidevine test [OPTIONS] DEVICE
+
+  Test the CDM code by getting Content Keys for Bitmovin's Art of Motion
+  example. https://bitmovin.com/demos/drm
+  https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd
+
+  The device argument is a Path to a Widevine Device (.wvd) file which
+  contains the device private key among other required information.
+
+Options:
+  -p, --privacy  Use Privacy Mode, off by default.
+  --help         Show this message and exit.
+```
 
 ## Disclaimer