update spectator-py docs for 1.0.3 (#194)

Top-level imports were added, which simplifies usage, so relevant examples
were updated. The main code examples were simplified a bit.

Author: copperlight

Diff for: docs/spectator/lang/py/meters/age-gauge.md

@@ -7,7 +7,7 @@ Time Since Last Success alerting pattern.
 To set a specific time as the last success:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.age_gauge("time.sinceLastSuccess").set(1611081000)
@@ -19,7 +19,7 @@ registry.age_gauge_with_id(last_success).set(1611081000)
 To set `now()` as the last success:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.age_gauge("time.sinceLastSuccess").now()

Diff for: docs/spectator/lang/py/meters/counter.md

@@ -7,7 +7,7 @@ be used to convert them back into a value-per-step on a graph.
 Call `increment()` when an event occurs:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.counter("server.numRequests").increment()
@@ -20,7 +20,7 @@ You can also pass a value to `increment()`. This is useful when a collection of
 together:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.counter("queue.itemsAdded").increment(10)

Diff for: docs/spectator/lang/py/meters/dist-summary.md

@@ -9,7 +9,7 @@ This means that a `4K` tick label will represent 4 kilobytes, rather than 4 kilo
 Call `record()` with a value:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.distribution_summary("server.requestSize").record(10)

Diff for: docs/spectator/lang/py/meters/gauge.md

@@ -9,7 +9,7 @@ higher or lower at some point during interval, but that is not known.
 Call `set()` with a value:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.gauge("server.queueSize").set(10)
@@ -23,7 +23,7 @@ not need to be collected on a tight 1-minute schedule to ensure that Atlas shows
 graphs. A custom TTL may be configured for gauges. SpectatorD enforces a minimum TTL of 5 seconds.
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.gauge("server.queueSize", ttl_seconds=120).set(10)

Diff for: docs/spectator/lang/py/meters/max-gauge.md

@@ -6,7 +6,7 @@ standard Gauges, Max Gauges do not continue to report to the backend, and there
 Call `set()` with a value:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.max_gauge("server.queueSize").set(10)

Diff for: docs/spectator/lang/py/meters/monotonic-counter-uint.md

@@ -8,7 +8,7 @@ Call `set()` when an event occurs:
 
 ```python
 from ctypes import c_uint64
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.monotonic_counter_uint("iface.bytes").set(c_uint64(1))

Diff for: docs/spectator/lang/py/meters/monotonic-counter.md

@@ -7,7 +7,7 @@ these values, at the expense of a slower time-to-first metric.
 Call `set()` when an event occurs:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.monotonic_counter("iface.bytes").set(10)

Diff for: docs/spectator/lang/py/meters/percentile-dist-summary.md

@@ -11,7 +11,7 @@ added to Percentile Distribution Summaries and ensure that they have a small bou
 Call `record()` with a value:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.pct_distribution_summary("server.requestSize").record(10)

Diff for: docs/spectator/lang/py/meters/percentile-timer.md

@@ -11,7 +11,7 @@ Timers and ensure that they have a small bounded cardinality.
 Call `record()` with a value:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.pct_timer("server.requestLatency").record(0.01)
@@ -25,8 +25,7 @@ the number of seconds that have elapsed while executing a block of code:
 
 ```python
 import time
-from spectator.registry import Registry
-from spectator.stopwatch import StopWatch
+from spectator import Registry, StopWatch
 
 registry = Registry()
 thread_sleep = registry.pct_timer("thread.sleep")

Diff for: docs/spectator/lang/py/meters/timer.md

@@ -3,7 +3,7 @@ A Timer is used to measure how long (in seconds) some event is taking.
 Call `record()` with a value:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.timer("server.requestLatency").record(0.01)
@@ -17,8 +17,7 @@ the number of seconds that have elapsed while executing a block of code:
 
 ```python
 import time
-from spectator.registry import Registry
-from spectator.stopwatch import StopWatch
+from spectator import Registry, StopWatch
 
 registry = Registry()
 thread_sleep = registry.timer("thread.sleep")

Diff for: docs/spectator/lang/py/migrations.md

@@ -63,8 +63,7 @@ After:
 
 ```python
 import time
-from spectator.registry import Registry
-from spectator.stopwatch import StopWatch
+from spectator import Registry, StopWatch
 
 registry = Registry()
 server_latency = registry.pct_timer("serverLatency")
@@ -99,7 +98,7 @@ GlobalRegistry.gauge("server.queueSize", ttl_seconds=120).set(10)
 After:
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.gauge("server.queueSize", ttl_seconds=120).set(10)

Diff for: docs/spectator/lang/py/usage.md

@@ -1,5 +1,7 @@
 # spectator-py Usage
 
+[![PyPI version](https://badge.fury.io/py/netflix-spectator-py.svg)](https://badge.fury.io/py/netflix-spectator-py)
+
 Python thin-client [metrics library] for use with [Atlas] and [SpectatorD].
 
 [metrics library]: https://github.com/Netflix/spectator-py
@@ -8,7 +10,7 @@ Python thin-client [metrics library] for use with [Atlas] and [SpectatorD].
 
 ## Supported Python Versions
 
-This library currently targets the Python >= 3.8.
+This library currently targets Python >= 3.8.
 
 ## Installing
 
@@ -27,7 +29,7 @@ import logging
 
 from flask import Flask, request, Response
 from flask.logging import default_handler
-from spectator.registry import Registry
+from spectator import Registry
 
 root_logger = logging.getLogger()
 root_logger.setLevel(logging.DEBUG)
@@ -41,12 +43,21 @@ app = Flask(__name__)
 def root():
     return Response("Usage: /api/v1/play?country=foo&title=bar")
 
-@app.route("/api/v1/play", methods=["GET", "POST"])
+@app.route("/api/v1/play")
 def play():
-    country = request.args.get("country", default="none")
-    title = request.args.get("title", default="none")
-    registry.counter("server.requestCount", {"version": "v1"}).increment()
-    return Response(f"requested play for country={country} title={title}")
+    country = request.args.get("country", default="unknown")
+    title = request.args.get("title", default="unknown")
+
+    if country == "unknown" or title == "unknown":
+        status = 404
+        message = f"invalid play request for country={country} title={title}"
+    else:
+        status = 200
+        message = f"requested play for country={country} title={title}"
+
+    tags = {"path": "v1_play", "country": country, "title": title, "status": str(status)}
+    registry.counter("server.requestCount", tags).increment()
+    return Response(message, status=status)
 ```
 
 Save this snippet as `app.py`, then `flask --app app run`.
@@ -58,52 +69,45 @@ import logging
 
 from flask import Flask, request, Response
 from flask.logging import default_handler
-from spectator.config import Config
-from spectator.registry import Registry
-from spectator.stopwatch import StopWatch
+from spectator import Config, Registry, StopWatch
 
 root_logger = logging.getLogger()
 root_logger.setLevel(logging.DEBUG)
 root_logger.addHandler(default_handler)
 
-config = Config(extra_common_tags={"nf.platform": "my_platform"})
+config = Config(extra_common_tags={"platform": "flask-demo"})
 registry = Registry(config)
 
-request_count_id = registry.new_id("server.requestCount", {"version": "v1"})
-request_latency = registry.timer("server.requestLatency")
-response_size = registry.distribution_summary("server.responseSize")
+request_count_id = registry.new_id("server.requestCount", {"path": "v1_play"})
+request_latency = registry.timer("server.requestLatency", {"path": "v1_play"})
+response_size = registry.distribution_summary("server.responseSize", {"path": "v1_play"})
 
 app = Flask(__name__)
 
 @app.route("/")
 def root():
     return Response("Usage: /api/v1/play?country=foo&title=bar")
 
-@app.route("/api/v1/play", methods=["GET", "POST"])
+@app.route("/api/v1/play")
 def play():
-    if request.method == "GET":
-        with StopWatch(request_latency):
-            status_code = 200
-            country = request.args.get("country", default="none")
-            title = request.args.get("title", default="none")
-
-            tags = {"country": country, "title": title, "status": str(status_code)}
-            request_count_with_tags = request_count_id.with_tags(tags)
-            counter = registry.counter_with_id(request_count_with_tags)
-            counter.increment()
-
+    with StopWatch(request_latency):
+        country = request.args.get("country", default="unknown")
+        title = request.args.get("title", default="unknown")
+
+        if country == "unknown" or title == "unknown":
+            status = 404
+            message = f"invalid play request for country={country} title={title}"
+        else:
+            status = 200
             message = f"requested play for country={country} title={title}"
-            response_size.record(len(message))
-            return Response(message, status=status_code)
-    else:
-        status_code = 405
 
-        tags = {"status": str(status_code)}
-        request_count_with_tags = request_count_id.with_tags(tags)
-        counter = registry.counter_with_id(request_count_with_tags)
-        counter.increment()
+        tags = {"country": country, "title": title, "status": str(status)}
+        request_count = registry.counter_with_id(request_count_id.with_tags(tags))
+
+        request_count.increment()
+        response_size.record(len(message))
 
-        return Response("unsupported request method", status=status_code)
+        return Response(message, status=status)
 ```
 
 Save this snippet as `app.py`, then `flask --app app run`.
@@ -116,7 +120,7 @@ Instantiate a `Registry` object, with either a default or custom `Config`, and u
 manage `MeterId` and `Meter` objects.
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.counter("server.requestCount").increment()
@@ -130,10 +134,10 @@ implement when adopting the thin client version of the library. It existed as a
 thick client because it was stateful, and required starting background threads. The thin client
 version is stateless. 
 
-Importing the `GlobalRegistry` instantiates a `Registry` with a default `Config` that applies
-process-specific common tags based on environment variables and opens a UDP socket to the local
-[SpectatorD] agent. The remainder of the instance-specific common tags are provided by [SpectatorD].
-Once imported, the `GlobalRegistry` can be used to create and manage Meters.
+Importing the `GlobalRegistry` instantiates a `Registry` with a default `Config`, and opens a UDP
+socket to the local [SpectatorD] agent when publishing metrics. The instance-specific common tags
+are provided by [SpectatorD]. Once imported, the `GlobalRegistry` can be used to create and manage
+Meters.
 
 ```python
 from spectator import GlobalRegistry
@@ -187,7 +191,7 @@ number of successful requests, then you must cast integers to strings. The `Mete
 validate these values, dropping or changing any that are not valid, and reporting a warning log.
 
 ```python
-from spectator.registry import Registry
+from spectator import Registry
 
 registry = Registry()
 registry.counter("server.numRequests", {"statusCode": str(200)}).increment()
@@ -247,8 +251,7 @@ export SPECTATOR_OUTPUT_LOCATION="udp://[::1]:1234"
 * Provide a custom `Config` for the `Registry`:
 
 ```python
-from spectator.config import Config
-from spectator.registry import Registry
+from spectator import Config, Registry
 
 config = Config(location="udp://[::1]:1234")
 registry = Registry(config)
@@ -318,8 +321,7 @@ updates.
 ```python
 import unittest
 
-from spectator.config import Config
-from spectator.registry import Registry
+from spectator import Config, Registry
 
 class MetricsTest(unittest.TestCase):
 
@@ -335,14 +337,13 @@ class MetricsTest(unittest.TestCase):
 
 ### Protocol Parser
 
-A [SpectatorD] line protocol parser is available, which ca be used for validating  the results
+A [SpectatorD] line protocol parser is available, which ca be used for validating the results
 captured by a `MemoryWriter`.
 
 ```python
 import unittest
 
-from spectator.meter.counter import Counter
-from spectator.protocol_parser import get_meter_class, parse_protocol_line
+from spectator import Counter, get_meter_class, parse_protocol_line
 
 class ProtocolParserTest(unittest.TestCase):