Services Module

Source: gitlab_overviewer.services.__init__.py

Services subpackage for gitlab_overviewer.

Implements Specification: Data Collection Workflow §1-4, covering:

• Data aggregation and business logic services for the overview pipeline

Business logic and data aggregation services for the overview pipeline.

• DataCollector – Aggregates data from GitLab and prepares it for rendering

• DataCollectorError – Error handling for data collection

See also: gitlab_overviewer.services.data_collector, gitlab_overviewer.services.readme_extraction, gitlab_overviewer.services.sort_utils

class gitlab_overviewer.services.DataCollector(client=None, *, include_subgroups=False)

Bases: object

Aggregate GitLab entities into OverviewData instances.

Parameters:

• client (GitLabClient | None) – Optional pre-configured GitLabClient. If None a new client is created from default settings.

• include_subgroups (bool) – Whether projects in sub-groups should be traversed. Currently not implemented (kept for future compatibility) and will raise NotImplementedError if True.

__init__(client=None, *, include_subgroups=False)

collect()

Return a list of OverviewData for all accessible projects, using all tokens.

Return type:

List[OverviewData]

exception gitlab_overviewer.services.DataCollectorError

Bases: RuntimeError

Raised when data-collection fails – wraps low-level API errors.

services.sort_utils

Source: gitlab_overviewer.services.sort_utils.py

Sorting utilities for table data.

Implements Specification: Table Sorting §1-8, covering:

• Sort-key definition and expressions (§1)

• General ordering rules (§2)

• Virtual arithmetic columns (§3)

• Date handling (§4)

• Missing values & dashes (§5)

• Group-aware post-processing (§6)

• Fallback sorting (§7)

• Error handling (§8)

gitlab_overviewer.services.sort_utils.parse_virtual_column(row, key)

Parse a virtual arithmetic column expression.

Supports operators +, -, * with proper precedence (* before +/-). Handles missing values and validates expression format.

Return type:

Optional[float]

gitlab_overviewer.services.sort_utils.parse_value(v, direction='asc')

gitlab_overviewer.services.sort_utils.is_virtual_column_sortable(overview_table, keys)

Check if a virtual column is sortable by validating that at least one row has numeric operands.

This function uses more restrictive validation than the spec minimum requirement. It requires ALL operands to be numeric for a row to be considered valid, whereas the spec only requires that not all operands evaluate to 0.

This provides better error detection by catching configuration issues earlier.

Parameters:

• overview_table (Dict[str, Dict[str, Any]]) – The table data to validate against

• keys (List[str]) – List of column keys or a single virtual column expression

Return type:

bool

Returns:

True if the virtual column is sortable, False otherwise

gitlab_overviewer.services.sort_utils.parse_sort_keys(sort_arg, table_config, overview_table=None)

Parse sort keys from command line argument or table configuration.

Sort keys can be specified in two formats: 1. <column-expr>:<direction> - e.g. “priority:desc” 2. <column-expr> - e.g. “priority” (defaults to “asc”)

Multiple sort keys can be comma-separated and are evaluated left-to-right as tiebreakers.

Parameters:

• sort_arg (Optional[str]) – Optional comma-separated list of sort keys from command line

• table_config (Optional[dict]) – Optional table configuration containing default sort keys

• overview_table (Optional[Dict[str, Dict[str, Any]]]) – Optional table data to validate sort keys against

Return type:

List[Tuple[str, str]]

Returns:

List of tuples (column_expr, direction) where direction is “asc” or “desc”

Raises:

SortConfigurationError – If sort configuration is invalid

gitlab_overviewer.services.sort_utils.sort_row_tuple(row, sort_keys)

Create a tuple for sorting that properly handles invalid rows.

Invalid rows are always placed after valid ones, regardless of sort direction.

gitlab_overviewer.services.sort_utils.sort_with_fallback(items, sort_keys)

Sort items by multiple keys with fallback.

Parameters:

• items (List[Tuple[str, Dict[str, Any]]]) – List of (id, row) tuples to sort

• sort_keys (List[Tuple[str, str]]) – List of (column_expr, direction) tuples

Returns:

Sorted list of items

Raises:

SortConfigurationError – If sort configuration is invalid

gitlab_overviewer.services.sort_utils.sort_overview(overview_data, table_config, sort_arg=None)

Sort OverviewData objects according to table_config and sort_arg.

Parameters:

• overview_data (List[OverviewData]) – List of OverviewData objects to sort

• table_config (dict) – Table configuration dict with columns and default_sort

• sort_arg (Optional[str]) – Optional sort argument from CLI (overrides default_sort)

Return type:

List[OverviewData]

Returns:

Sorted list of OverviewData objects

services.readme_extraction

Source: gitlab_overviewer.services.readme_extraction.py

Utility for extracting interpreted information from README content into ReadmeExtract.

Implements Specification: ReadmeExtract Model §1-7, covering:

• Class definition and field extraction (§1-2)

• Authors/supervisors processing (§3)

• Construction process (§4)

• Integration with Readme model (§5)

• Error handling (§6)

• Examples and non-goals (§7-8)

gitlab_overviewer.services.readme_extraction.parse_readme(content, mode='full')

Parse README content and extract structured information.

Parameters:

• content (str) – The README content to parse

• mode (str) – Parsing mode (“full”, “todo”, etc.)

Returns:

• front_matter: Extracted YAML frontmatter

• content: Main content without frontmatter

Return type:

Dictionary containing parsed information with keys

gitlab_overviewer.services.readme_extraction.extract_readme_data(content, todo_keywords=None)

Extract interpreted information from README content and return a ReadmeExtract object.

Only authors, supervisors and raw front-matter are returned per the strict specification. Any additional metadata is ignored at this stage.

Return type:

ReadmeExtract

gitlab_overviewer.services.readme_extraction.extract_first_paragraph(content)

Return type:

str | None

gitlab_overviewer.services.readme_extraction.extract_todo_sections(content, todo_keywords)

Extract TODO sections from README content based on keywords.

Parameters:

• content (str) – The README content to parse

• todo_keywords (list[str]) – List of keywords to search for (e.g., [“todo”, “status”, “stand”])

Return type:

str | None

Returns:

Extracted TODO sections as markdown text, or None if no sections found

services.data_collector

Source: gitlab_overviewer.services.data_collector.py

class gitlab_overviewer.services.data_collector.DataCollector(client=None, *, include_subgroups=False)

Bases: object

Aggregate GitLab entities into OverviewData instances.

Parameters:

• client (GitLabClient | None) – Optional pre-configured GitLabClient. If None a new client is created from default settings.

• include_subgroups (bool) – Whether projects in sub-groups should be traversed. Currently not implemented (kept for future compatibility) and will raise NotImplementedError if True.

__init__(client=None, *, include_subgroups=False)

collect()

Return a list of OverviewData for all accessible projects, using all tokens.

Return type:

List[OverviewData]

exception gitlab_overviewer.services.data_collector.DataCollectorError

Bases: RuntimeError

Raised when data-collection fails – wraps low-level API errors.