Regions

Hierarchical code region model (file → class → function → lines).

Hierarchical code region model for curate-ipsum.

Regions identify code locations at various granularities: - File level: file:src/main.py - Class level: file:src/main.py::class:Calculator - Function level: file:src/main.py::func:compute - Line range: file:src/main.py::lines:10-25

Regions support containment queries (does region A contain region B?) and overlap detection for aggregating metrics across related code.

class curate_ipsum.regions.Region(file_path, class_name=None, func_name=None, line_start=None, line_end=None)[source]

Bases: object

Hierarchical code region identifier.

Immutable, hashable, and serializable to/from string. Supports containment queries (is region A within region B?).

Format:

file:<path> # Whole file file:<path>::class:<name> # Class level file:<path>::func:<name> # Function level file:<path>::class:<name>::func:<name> # Method within class file:<path>::lines:<start>-<end> # Line range

Examples

>>> Region.for_file("src/main.py")
Region('file:src/main.py')

>>> Region.for_function("src/main.py", "compute", class_name="Calculator")
Region('file:src/main.py::class:Calculator::func:compute')

>>> r = Region.from_string("file:src/main.py::lines:10-20")
>>> r.line_start
10
Parameters:

  • file_path (str)

  • class_name (str | None)

  • func_name (str | None)

  • line_start (int | None)

  • line_end (int | None)

file_path: str
class_name: str | None = None
func_name: str | None = None
line_start: int | None = None
line_end: int | None = None
property level: RegionLevel

Most specific level of this region.

contains(other)[source]

Check if this region contains another region.

A region contains another if: - Same file AND - This region’s scope encompasses the other’s scope

Examples

file:a.py contains file:a.py::func:foo # True file:a.py::class:C contains file:a.py::class:C::func:m # True file:a.py::func:foo contains file:a.py # False

Parameters:

other (Region)

Return type:

bool

overlaps(other)[source]

Check if this region overlaps with another.

Two regions overlap if they share any code locations.

Parameters:

other (Region)

Return type:

bool

to_string()[source]

Serialize to canonical string format.

The format is designed to be: - Human readable - Lexicographically sortable by file - Parseable back to Region

Return type:

str

classmethod from_string(s)[source]

Parse from canonical string format.

Also handles legacy plain file paths for backward compatibility.

Parameters:

s (str) – Region string like “file:src/main.py::func:compute” or legacy plain path like “src/main.py”

Returns:

Parsed Region instance

Raises:

ValueError – If string is empty or malformed

Return type:

Region

classmethod for_file(path)[source]

Create a file-level region.

Parameters:

path (str)

Return type:

Region

classmethod for_class(path, class_name)[source]

Create a class-level region.

Parameters:
Return type:

Region

classmethod for_function(path, func_name, class_name=None)[source]

Create a function-level region.

Parameters:

  • path (str)

  • func_name (str)

  • class_name (str | None)

Return type:

Region

classmethod for_lines(path, start, end, func_name=None, class_name=None)[source]

Create a line-range region.

Parameters:

  • path (str)

  • start (int)

  • end (int)

  • func_name (str | None)

  • class_name (str | None)

Return type:

Region

class curate_ipsum.regions.RegionLevel(*values)[source]

Bases: StrEnum

Granularity level of a region.

FILE = 'file'
CLASS = 'class'
FUNCTION = 'func'
LINES = 'lines'
curate_ipsum.regions.normalize_region_id(region_id)[source]

Convert legacy regionId string to Region, or return None.

Provides backward compatibility with existing regionId: str fields.

Parameters:

region_id (str | None)

Return type:

Region | None

curate_ipsum.regions.region_to_id(region)[source]

Convert Region back to string for storage.

Inverse of normalize_region_id.

Parameters:

region (Region | None)

Return type:

str | None

Hierarchical code region model.

Inspired by pytest’s node ID format (well-established, familiar to Python developers). Supports serialization to/from strings for storage compatibility.

class curate_ipsum.regions.models.RegionLevel(*values)[source]

Bases: StrEnum

Granularity level of a region.

FILE = 'file'
CLASS = 'class'
FUNCTION = 'func'
LINES = 'lines'
class curate_ipsum.regions.models.Region(file_path, class_name=None, func_name=None, line_start=None, line_end=None)[source]

Bases: object

Hierarchical code region identifier.

Immutable, hashable, and serializable to/from string. Supports containment queries (is region A within region B?).

Format:

file:<path> # Whole file file:<path>::class:<name> # Class level file:<path>::func:<name> # Function level file:<path>::class:<name>::func:<name> # Method within class file:<path>::lines:<start>-<end> # Line range

Examples

>>> Region.for_file("src/main.py")
Region('file:src/main.py')

>>> Region.for_function("src/main.py", "compute", class_name="Calculator")
Region('file:src/main.py::class:Calculator::func:compute')

>>> r = Region.from_string("file:src/main.py::lines:10-20")
>>> r.line_start
10
Parameters:

  • file_path (str)

  • class_name (str | None)

  • func_name (str | None)

  • line_start (int | None)

  • line_end (int | None)

file_path: str
class_name: str | None = None
func_name: str | None = None
line_start: int | None = None
line_end: int | None = None
property level: RegionLevel

Most specific level of this region.

contains(other)[source]

Check if this region contains another region.

A region contains another if: - Same file AND - This region’s scope encompasses the other’s scope

Examples

file:a.py contains file:a.py::func:foo # True file:a.py::class:C contains file:a.py::class:C::func:m # True file:a.py::func:foo contains file:a.py # False

Parameters:

other (Region)

Return type:

bool

overlaps(other)[source]

Check if this region overlaps with another.

Two regions overlap if they share any code locations.

Parameters:

other (Region)

Return type:

bool

to_string()[source]

Serialize to canonical string format.

The format is designed to be: - Human readable - Lexicographically sortable by file - Parseable back to Region

Return type:

str

classmethod from_string(s)[source]

Parse from canonical string format.

Also handles legacy plain file paths for backward compatibility.

Parameters:

s (str) – Region string like “file:src/main.py::func:compute” or legacy plain path like “src/main.py”

Returns:

Parsed Region instance

Raises:

ValueError – If string is empty or malformed

Return type:

Region

classmethod for_file(path)[source]

Create a file-level region.

Parameters:

path (str)

Return type:

Region

classmethod for_class(path, class_name)[source]

Create a class-level region.

Parameters:
Return type:

Region

classmethod for_function(path, func_name, class_name=None)[source]

Create a function-level region.

Parameters:

  • path (str)

  • func_name (str)

  • class_name (str | None)

Return type:

Region

classmethod for_lines(path, start, end, func_name=None, class_name=None)[source]

Create a line-range region.

Parameters:

  • path (str)

  • start (int)

  • end (int)

  • func_name (str | None)

  • class_name (str | None)

Return type:

Region

curate_ipsum.regions.models.normalize_region_id(region_id)[source]

Convert legacy regionId string to Region, or return None.

Provides backward compatibility with existing regionId: str fields.

Parameters:

region_id (str | None)

Return type:

Region | None

curate_ipsum.regions.models.region_to_id(region)[source]

Convert Region back to string for storage.

Inverse of normalize_region_id.

Parameters:

region (Region | None)

Return type:

str | None