task: lint and doc

Author: lilatomic

alpacloud/promls/cli.py

@@ -1,3 +1,5 @@
+"""CLI interface for promls."""
+
 import enum
 import itertools
 import json
@@ -13,13 +15,16 @@
 
 
 class PrintMode(enum.StrEnum):
+	"""Output format"""
+
 	flat = "flat"
 	tree = "tree"
 	full = "full"
 	json = "json"
 
 	@staticmethod
 	def parse(ctx, param, value):
+		"""Parse from click"""
 		# Normalize and map to the enum so command handlers receive PrintMode
 		if value is None:
 			return None
@@ -39,6 +44,8 @@ def parse(ctx, param, value):
 
 
 def common_args():
+	"""Common arguments for search commands"""
+
 	def decorator(f):
 		f = opt_filter(f)
 		f = opt_mode(f)
@@ -49,14 +56,17 @@ def decorator(f):
 
 
 def do_fetch(url: str):
+	"""Do the fetch and parse."""
 	return MetricsTree(Parser().parse(FetcherURL(url).fetch()))
 
 
 def mk_indent(i: int, s: str) -> str:
+	"""Indent a line"""
 	return "\t" * i + s
 
 
 def render_metric(m: Metric) -> str:
+	"""Render a metric in a human-readable format."""
 	return f"{m.name} ({m.type}) {m.help or ''}"
 
 

alpacloud/promls/fetch.py

@@ -29,6 +29,8 @@ def fetch(self):
 
 
 class ParseError(Exception):
+	"""Error parsing Prometheus metrics endpoint."""
+
 	def __init__(self, value, line: str):
 		self.line = line
 		super().__init__(value)
@@ -40,10 +42,6 @@ def __str__(self) -> str:
 class Parser:
 	"""Parse metrics from Prometheus metrics endpoint."""
 
-	class State(Enum):
-		metadata = "metadata"
-		data = "data"
-
 	@dataclass
 	class DataLine:
 		"""Data line from Prometheus metrics endpoint."""
@@ -54,6 +52,8 @@ class DataLine:
 		timestamp: int | None = None
 
 	class MetaKind(Enum):
+		"""Kind of the line of metadata."""
+
 		HELP = "HELP"
 		TYPE = "TYPE"
 		COMMENT = "COMMENT"
@@ -72,6 +72,7 @@ def parse(self, lines: list[str]) -> dict[str, Metric]:
 		return {k: self.parse_metric(k, v) for k, v in name2data.items()}
 
 	def group_lines(self, lines: list[str]):
+		"""Group lines by the metric name."""
 		name2data = defaultdict(list)
 		for line in lines:
 			# escape empty lines
@@ -90,6 +91,7 @@ def group_lines(self, lines: list[str]):
 
 	@staticmethod
 	def parse_data_line(line: str) -> DataLine:
+		"""Subparser for a line of data."""
 		# TODO: handle escaping in lines
 		x = line.split(" ", 1)
 		if len(x) != 2:
@@ -125,6 +127,7 @@ def parse_data_line(line: str) -> DataLine:
 
 	@staticmethod
 	def parse_meta_line(line: str) -> MetaLine:
+		"""Subparser for a line of metadata."""
 		if not line.startswith("#"):
 			raise ParseError(r"Invalid metadata line, did not start with #")
 
@@ -145,6 +148,7 @@ def parse_meta_line(line: str) -> MetaLine:
 
 	@staticmethod
 	def parse_metric(name, statements: list[Parser.DataLine | Parser.MetaLine]) -> Metric:
+		"""Subpaarser for an actual metric."""
 		# TODO: label sets
 		# TODO: sample values
 

alpacloud/promls/filter.py

@@ -1,3 +1,5 @@
+"""Filter metrics."""
+
 from __future__ import annotations
 
 import logging
@@ -14,33 +16,44 @@
 
 @dataclass
 class MetricsTree:
+	"""A tree of metrics."""
+
 	metrics: dict[str, Metric]
 
 	@classmethod
 	def mk_tree(cls, metrics: list[Metric]) -> MetricsTree:
+		"""
+		Construct a metrics tree from a list of metrics.
+		"""
 		return cls(
 			{e.name: e for e in metrics},
 		)
 
 	def filter(self, predicate: Predicate) -> MetricsTree:
+		"""Filter this metrics tree."""
 		return MetricsTree({k: v for k, v in self.metrics.items() if predicate(v)})
 
 
 def filter_name(pattern: re.Pattern) -> Predicate:
+	"""Filter metrics for name"""
+
 	def predicate(metric: Metric) -> bool:
 		return pattern.search(metric.name) is not None
 
 	return predicate
 
 
 def filter_any(pattern: re.Pattern) -> Predicate:
+	"""Filter metrics for any field"""
+
 	def predicate(metric: Metric) -> bool:
 		return pattern.search(metric.name) is not None or pattern.search(metric.help) is not None
 
 	return predicate
 
 
 def filter_path(path: list[str]) -> Predicate:
+	"""Filter metrics for path components."""
 	pattern = re.compile("^" + "_".join(path))
 
 	def predicate(metric: Metric) -> bool:

alpacloud/promls/filter_test.py

@@ -1,6 +1,6 @@
 import re
 
-from alpacloud.promls.filter import filter_name
+from alpacloud.promls.filter import filter_any, filter_name, filter_path
 from alpacloud.promls.metrics import Metric
 
 
@@ -48,69 +48,47 @@ def test_search_ignores_helptext(self):
 
 class TestFilterAny:
 	def test_matches_when_pattern_in_name(self):
-		from filter import filter_any
-
 		predicate = filter_any(re.compile("latency"))
 		assert predicate(Metric("http_latency_seconds", "HTTP request latency", "histogram")) is True
 
 	def test_matches_when_pattern_in_help(self):
-		from filter import filter_any
-
 		predicate = filter_any(re.compile(r"request latency"))
 		assert predicate(Metric("http_seconds", "HTTP request latency", "histogram")) is True
 
 	def test_does_not_match_when_neither_name_nor_help_match(self):
-		from filter import filter_any
-
 		predicate = filter_any(re.compile("throughput"))
 		assert predicate(Metric("http_latency_seconds", "HTTP request latency", "histogram")) is False
 
 	def test_case_insensitive_with_flag(self):
-		from filter import filter_any
-
 		predicate = filter_any(re.compile("LATENCY", re.IGNORECASE))
 		assert predicate(Metric("http_latency_seconds", "HTTP request latency", "histogram")) is True
 
 	def test_empty_pattern_matches_everything(self):
-		from filter import filter_any
-
 		predicate = filter_any(re.compile(""))
 		assert predicate(Metric("anything", "and everything", "counter")) is True
 
 
 class TestFilterPath:
 	def test_matches_prefix_path(self):
-		from filter import filter_path
-
 		predicate = filter_path(["http", "server"])
 		assert predicate(Metric("http_server_requests_total", "Total HTTP server requests", "counter")) is True
 
 	def test_does_not_match_when_prefix_not_at_start(self):
-		from filter import filter_path
-
 		predicate = filter_path(["http", "server"])
 		assert predicate(Metric("xhttp_server_requests_total", "prefixed with x", "counter")) is False
 
 	def test_does_not_match_different_prefix(self):
-		from filter import filter_path
-
 		predicate = filter_path(["http", "server"])
 		assert predicate(Metric("http_client_requests_total", "client metric", "counter")) is False
 
 	def test_exact_match(self):
-		from filter import filter_path
-
 		predicate = filter_path(["http", "server"])
 		assert predicate(Metric("http_server", "exact match", "gauge")) is True
 
 	def test_longer_path_matches(self):
-		from filter import filter_path
-
 		predicate = filter_path(["a", "b", "c"])
 		assert predicate(Metric("a_b_c_d", "longer metric name", "counter")) is True
 
 	def test_case_sensitive_by_default(self):
-		from filter import filter_path
-
 		predicate = filter_path(["HTTP", "server"])
 		assert predicate(Metric("http_server_requests_total", "lowercase name", "counter")) is False

alpacloud/promls/metrics.py

@@ -1,3 +1,5 @@
+"""Definitions for Prometheus metrics."""
+
 from dataclasses import dataclass
 
 

alpacloud/promls/util.py

@@ -1,8 +1,11 @@
+"""Generic utilities."""
+
 import functools
 from typing import Any, Dict, Mapping, Optional, TypeVar
 
 
 def compose(*funcs):
+	"""Sequentially compose functions."""
 	return functools.reduce(lambda f, g: lambda x: f(g(x)), funcs)
 
 

alpacloud/promls/vis.py

@@ -1,5 +1,4 @@
 import re
-from typing import Callable
 
 from textual.app import App, ComposeResult
 from textual.binding import Binding
@@ -96,7 +95,6 @@ async def action_goto(self):
 		self.load_metrics(self.metrics)
 		self.focus_findbox()
 
-
 	def action_expand_all(self) -> None:
 		"""Expand all nodes in the tree."""
 		tree = self.query_one(Tree)