docs: document CodeRegion and its plugin methods

coverage/__init__.py

@@ -28,6 +28,7 @@
 from coverage.data import CoverageData as CoverageData
 from coverage.exceptions import CoverageException as CoverageException
 from coverage.plugin import (
+ CodeRegion as CodeRegion,
  CoveragePlugin as CoveragePlugin,
  FileReporter as FileReporter,
  FileTracer as FileTracer,

coverage/plugin.py

@@ -114,16 +114,15 @@ def coverage_init(reg, options):
 
 from __future__ import annotations
 
+import dataclasses
 import functools
 
 from types import FrameType
 from typing import Any, Iterable
 
 from coverage import files
 from coverage.misc import _needs_to_implement
-from coverage.types import (
- CodeRegion, TArc, TConfigurable, TLineNo, TSourceTokenLines,
-)
+from coverage.types import TArc, TConfigurable, TLineNo, TSourceTokenLines
 
 
 class CoveragePlugin:
@@ -346,6 +345,35 @@ def line_number_range(self, frame: FrameType) -> tuple[TLineNo, TLineNo]:
  return lineno, lineno
 
 
+@dataclasses.dataclass
+class CodeRegion:
+ """Data for a region of code found by :meth:`FileReporter.code_regions`."""
+
+ #: The kind of region, like `"function"` or `"class"`. Must be one of the
+ #: singular values returned by :meth:`FileReporter.code_region_kinds`.
+ kind: str
+
+ #: The name of the region. For example, a function or class name.
+ name: str
+
+ #: The line in the source file to link to when navigating to the region.
+ #: Can be a line not mentioned in `lines`.
+ start: int
+
+ #: The lines in the region. Should be lines that could be executed in the
+ #: region. For example, a class region includes all of the lines in the
+ #: methods of the class, but not the lines defining class attributes, since
+ #: they are executed on import, not as part of exercising the class. The
+ #: set can include non-executable lines like blanks and comments.
+ lines: set[int]
+
+ def __lt__(self, other: CodeRegion) -> bool:
+ """To support sorting to make test-writing easier."""
+ if self.name == other.name:
+ return min(self.lines) < min(other.lines)
+ return self.name < other.name
+
+
 @functools.total_ordering
 class FileReporter(CoveragePluginBase):
  """Support needed for files during the analysis and reporting phases.
@@ -546,11 +574,28 @@ def source_token_lines(self) -> TSourceTokenLines:
  yield [("txt", line)]
 
  def code_regions(self) -> Iterable[CodeRegion]:
- """TODO XXX"""
+ """Identify regions in the source file for finer reporting than by file.
+
+ Returns an iterable of :class:`CodeRegion` objects. The kinds reported
+ should be in the possibilities returned by :meth:`code_region_kinds`.
+
+ """
  return []
 
  def code_region_kinds(self) -> Iterable[tuple[str, str]]:
- """TODO XXX"""
+ """Return the kinds of code regions this plugin can find.
+
+ The returned pairs are the singular and plural forms of the kinds::
+
+ [
+ ("function", "functions"),
+ ("class", "classes"),
+ ]
+
+ This will usually be hard-coded, but could also differ by the specific
+ source file involved.
+
+ """
  return []
 
  def __eq__(self, other: Any) -> bool:

coverage/regions.py

@@ -10,7 +10,7 @@
 
 from typing import cast
 
-from coverage.types import CodeRegion
+from coverage.plugin import CodeRegion
 
 
 @dataclasses.dataclass
@@ -91,22 +91,14 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:
 def code_regions(source: str) -> list[CodeRegion]:
  """Find function and class regions in source code.
 
- TODO: Fix this description.
-
- Takes the program `source`, and returns a dict: the keys are "function" and
- "class". Each has a value which is a dict: the keys are fully qualified
- names, the values are sets of line numbers included in that region::
-
- {
- "function": {
- "func1": {10, 11, 12},
- "func2": {20, 21, 22},
- "MyClass.method: {34, 35, 36},
- },
- "class": {
- "MyClass": {34, 35, 36},
- },
- }
+ Analyzes the code in `source`, and returns a list of :class:`CodeRegion`
+ objects describing functions and classes as regions of the code::
+
+ [
+ CodeRegion(kind="function", name="func1", start=8, lines={10, 11, 12}),
+ CodeRegion(kind="function", name="MyClass.method", start=30, lines={34, 35, 36}),
+ CodeRegion(kind="class", name="MyClass", start=25, lines={34, 35, 36}),
+ ]
 
  The line numbers will include comments and blank lines. Later processing
  will need to ignore those lines as needed.

coverage/types.py

@@ -7,7 +7,6 @@
 
 from __future__ import annotations
 
-import dataclasses
 import os
 import pathlib
 
@@ -163,27 +162,6 @@ def get_plugin_options(self, plugin: str) -> TConfigSectionOut:
 TSourceTokenLines = Iterable[List[Tuple[str, str]]]
 
 
-@dataclasses.dataclass
-class CodeRegion:
- """Data for each region found by FileReporter.code_regions.
-
- `kind`: the kind of region.
- `name`: the description of the region.
- `start`: the first line of the named region.
- `lines`: a super-set of the executable source lines in the region.
- """
- kind: str
- name: str
- start: int
- lines: set[int]
-
- def __lt__(self, other: CodeRegion) -> bool:
- """To support sorting to make test-writing easier."""
- if self.name == other.name:
- return min(self.lines) < min(other.lines)
- return self.name < other.name
-
-
 ## Plugins
 
 class TPlugin(Protocol):

doc/api_plugin.rst

@@ -32,3 +32,10 @@ The FileReporter class
 .. autoclass:: FileReporter
  :members:
  :member-order: bysource
+
+The CodeRegion class
+--------------------
+
+.. autoclass:: CodeRegion
+ :members:
+ :member-order: bysource