Models Module

Source: gitlab_overviewer.models.__init__.py

Domain models for gitlab_overviewer.

Provides data structures for groups, projects, issues, and readme extraction.

Implements Specification: Model Mapping Layer §1-5, covering:

• Group – GitLab group model

• Project – GitLab project model

• Issue – GitLab issue model

• Readme – Project readme model

• ReadmeExtract – Extracted readme content

• OverviewData – Aggregated overview data

See also: gitlab_overviewer.models.group, gitlab_overviewer.models.project, gitlab_overviewer.models.issue, gitlab_overviewer.models.readme, gitlab_overviewer.models.readme_extract, gitlab_overviewer.models.overview_data

class gitlab_overviewer.models.Group(**data)

Bases: BaseModel

GitLab Group domain model.

Implements Specification: Model Mapping Layer §2.1, mapping the following fields:

• id (str) - Preserved as string for consistency

• name (str)

classmethod coerce_id_to_str(v)

classmethod from_api_json(data)

Create Group from GitLab API JSON dict.

Return type:

Group

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

name: str

path: str | None

web_url: str | None

description: str | None

visibility: str | None

class gitlab_overviewer.models.Project(**data)

Bases: BaseModel

GitLab Project domain model.

Implements Specification: Model Mapping Layer §2.2, mapping the following fields:

• id (int)

• name (str)

• path_with_namespace (str, optional)

• default_branch (str, optional)

• last_activity_at (datetime) - Parsed to UTC

• namespace (Group) - namespace parsed as group if possible.

classmethod from_api_json(data)

Create Project from API JSON with robust type handling.

Return type:

Project

get_avatar_html(width=16)

Generate HTML for avatar image if available.

Return type:

str

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_dump(**kwargs)

Override to include computed fields.

Return type:

dict[str, Any]

classmethod validate_datetime_fields(v)

Convert string dates to datetime if needed.

Return type:

datetime | None

classmethod validate_group_fields(v)

Convert group-dict to group.

Return type:

Group | None

classmethod validate_int_fields(v)

Convert string/integer mismatches for numeric fields.

Return type:

int | None

id: int

name: str

description: str | None

web_url: str | None

path: str | None

path_with_namespace: str | None

last_activity_at: datetime | None

default_branch: str | None

visibility: str | None

readme_url: str | None

avatar_url: str | None

namespace: Group | None

class gitlab_overviewer.models.Issue(**data)

Bases: BaseModel

GitLab Issue domain model.

Implements Specification: Model Mapping Layer §2.3, mapping the following fields:

• id (int) - Must be interpretable as int

• iid (int) - Must be interpretable as int

• project_id (int) - Must be interpretable as int

• title (str)

• state (str, optional)

• web_url (str, optional)

• description (str, optional)

classmethod from_api_json(data)

Return type:

Issue

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_iid(v)

Ensure iid is an int, throw error if not possible.

Return type:

int

classmethod validate_int_fields(v)

Convert string/integer mismatches for numeric fields.

Return type:

int | None

id: int

iid: int

project_id: int

title: str

description: str | None

state: str | None

web_url: str | None

class gitlab_overviewer.models.Readme(**data)

Bases: BaseModel

Readme model with content and metadata.

Implements: * Specification: Model Mapping Layer §2.4, mapping raw content to structured fields * Specification: ReadmeExtract Model §2-3, handling:

• Content extraction (§2)

• Metadata parsing (§3)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

project_id: int

content: str

todo: str | None

full_content: str

extra: ReadmeExtract

ref: str

path: str

class gitlab_overviewer.models.ReadmeExtract(**data)

Bases: BaseModel

Extracted and interpreted information from README frontmatter.

Implements:

• Specification: Model Mapping Layer §4, handling derived metadata

• Specification: ReadmeExtract Model §3, covering: * Frontmatter parsing * Author/supervisor extraction

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

authors: list[str]

supervisors: list[str]

raw_frontmatter: dict[str, Any]

class gitlab_overviewer.models.OverviewData(**data)

Bases: BaseModel

Container for all data related to a project overview.

Implements Specification: Table Rendering & UI §2, providing:

• Computed column values (repo, type, priority, urgency, etc.)

• Formatted cell values (dates, star ratings, issue counts)

• Placeholder handling for missing data

get_date()

Get formatted date from project or extra data.

Return type:

str

get_importance()

Get importance from extra data.

Return type:

int | None

get_importance_stars()

Get importance as star rating.

Return type:

str

get_issue_summary()

Format issue counts for display.

Return type:

str

get_priority()

Get priority from extra data.

Return type:

int | None

get_priority_stars()

Get priority as star rating.

Return type:

str

get_repo()

Get repository name.

Return type:

str

get_status()

Get status from extra data.

Return type:

str

get_supervisors()

Get supervisors from extra data.

Return type:

str

get_todos()

Get todos from extra data.

Return type:

str

get_type()

Get type from extra data.

Return type:

str

get_urgency()

Get urgency from extra data.

Return type:

int | None

get_urgency_stars()

Get urgency as star rating.

Return type:

str

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_dump(**kwargs)

Convert to dict with computed fields for rendering.

Return type:

dict[str, Any]

group: Group

project: Project

readme: Readme | None

issues: Optional[List[Issue]]

extra: ReadmeExtract

models.overview_data

Source: gitlab_overviewer.models.overview_data.py

Overview data model implementation.

Implements Specification: Table Rendering & UI §2-3, covering: - Column value computation (§2) - Placeholder handling (§3)

class gitlab_overviewer.models.overview_data.OverviewData(**data)

Bases: BaseModel

Container for all data related to a project overview.

Implements Specification: Table Rendering & UI §2, providing:

• Computed column values (repo, type, priority, urgency, etc.)

• Formatted cell values (dates, star ratings, issue counts)

• Placeholder handling for missing data

group: Group

project: Project

readme: Readme | None

issues: Optional[List[Issue]]

extra: ReadmeExtract

model_dump(**kwargs)

Convert to dict with computed fields for rendering.

Return type:

dict[str, Any]

get_repo()

Get repository name.

Return type:

str

get_supervisors()

Get supervisors from extra data.

Return type:

str

get_status()

Get status from extra data.

Return type:

str

get_todos()

Get todos from extra data.

Return type:

str

get_type()

Get type from extra data.

Return type:

str

get_priority()

Get priority from extra data.

Return type:

int | None

get_urgency()

Get urgency from extra data.

Return type:

int | None

get_importance()

Get importance from extra data.

Return type:

int | None

get_priority_stars()

Get priority as star rating.

Return type:

str

get_urgency_stars()

Get urgency as star rating.

Return type:

str

get_importance_stars()

Get importance as star rating.

Return type:

str

get_issue_summary()

Format issue counts for display.

Return type:

str

get_date()

Get formatted date from project or extra data.

Return type:

str

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models.project

Source: gitlab_overviewer.models.project.py

GitLab Project model implementation.

Implements Specification: Model Mapping Layer §2.2 for Project entity mapping.

class gitlab_overviewer.models.project.Project(**data)

Bases: BaseModel

GitLab Project domain model.

Implements Specification: Model Mapping Layer §2.2, mapping the following fields:

• id (int)

• name (str)

• path_with_namespace (str, optional)

• default_branch (str, optional)

• last_activity_at (datetime) - Parsed to UTC

• namespace (Group) - namespace parsed as group if possible.

id: int

name: str

description: str | None

web_url: str | None

path: str | None

path_with_namespace: str | None

last_activity_at: datetime | None

default_branch: str | None

visibility: str | None

readme_url: str | None

avatar_url: str | None

namespace: Group | None

classmethod validate_int_fields(v)

Convert string/integer mismatches for numeric fields.

Return type:

int | None

classmethod validate_group_fields(v)

Convert group-dict to group.

Return type:

Group | None

classmethod validate_datetime_fields(v)

Convert string dates to datetime if needed.

Return type:

datetime | None

get_avatar_html(width=16)

Generate HTML for avatar image if available.

Return type:

str

classmethod from_api_json(data)

Create Project from API JSON with robust type handling.

Return type:

Project

model_dump(**kwargs)

Override to include computed fields.

Return type:

dict[str, Any]

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models.group

Source: gitlab_overviewer.models.group.py

GitLab Group model implementation.

Implements Specification: Model Mapping Layer §2.1 for Group entity mapping.

class gitlab_overviewer.models.group.Group(**data)

Bases: BaseModel

GitLab Group domain model.

Implements Specification: Model Mapping Layer §2.1, mapping the following fields:

• id (str) - Preserved as string for consistency

• name (str)

id: str

name: str

path: str | None

web_url: str | None

description: str | None

visibility: str | None

classmethod coerce_id_to_str(v)

classmethod from_api_json(data)

Create Group from GitLab API JSON dict.

Return type:

Group

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models.issue

Source: gitlab_overviewer.models.issue.py

GitLab Issue model implementation.

Implements Specification: Model Mapping Layer §2.3 for Issue entity mapping.

class gitlab_overviewer.models.issue.Issue(**data)

Bases: BaseModel

GitLab Issue domain model.

Implements Specification: Model Mapping Layer §2.3, mapping the following fields:

• id (int) - Must be interpretable as int

• iid (int) - Must be interpretable as int

• project_id (int) - Must be interpretable as int

• title (str)

• state (str, optional)

• web_url (str, optional)

• description (str, optional)

id: int

iid: int

project_id: int

title: str

description: str | None

state: str | None

web_url: str | None

classmethod validate_iid(v)

Ensure iid is an int, throw error if not possible.

Return type:

int

classmethod validate_int_fields(v)

Convert string/integer mismatches for numeric fields.

Return type:

int | None

classmethod from_api_json(data)

Return type:

Issue

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models.readme

Source: gitlab_overviewer.models.readme.py

Readme model implementation.

Implements: - Specification: Model Mapping Layer §2.4 for Readme entity mapping - Specification: ReadmeExtract Model for content processing

class gitlab_overviewer.models.readme.Readme(**data)

Bases: BaseModel

Readme model with content and metadata.

Implements: * Specification: Model Mapping Layer §2.4, mapping raw content to structured fields * Specification: ReadmeExtract Model §2-3, handling:

• Content extraction (§2)

• Metadata parsing (§3)

project_id: int

content: str

todo: str | None

full_content: str

extra: ReadmeExtract

ref: str

path: str

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models.readme_extract

Source: gitlab_overviewer.models.readme_extract.py

ReadmeExtract model implementation.

Implements:

• Specification: Model Mapping Layer §4 for derived metadata extraction

• Specification: ReadmeExtract Model §3 for metadata parsing

class gitlab_overviewer.models.readme_extract.ReadmeExtract(**data)

Bases: BaseModel

Extracted and interpreted information from README frontmatter.

Implements:

• Specification: Model Mapping Layer §4, handling derived metadata

• Specification: ReadmeExtract Model §3, covering: * Frontmatter parsing * Author/supervisor extraction

authors: list[str]

supervisors: list[str]

raw_frontmatter: dict[str, Any]

model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models.mapper

Source: gitlab_overviewer.models.mapper.py

Model mapping implementation.

Implements Specification: Model Mapping Layer §1-5, covering:

• General mapping rules (§1)

• Entity-specific details (§2)

• Content extraction rules (§3)

• Derived metadata extraction (§4)

• Error handling (§5)

gitlab_overviewer.models.mapper.group_from_json(data)

Return type:

Group

gitlab_overviewer.models.mapper.project_from_json(data)

Return type:

Project

gitlab_overviewer.models.mapper.issue_from_json(data)

Return type:

Issue

gitlab_overviewer.models.mapper.readme_from_str(project_id, content, ref='main', path='README.md')

Create Readme from content string with extracted metadata.

Return type:

Readme

gitlab_overviewer.models.mapper._parse_dates(data)

Return data copy with ISO date strings converted to datetime.

Return type:

dict[str, Any]

gitlab_overviewer.models.mapper._robust_type_conversion(data)

Convert types and handle nulls/str/int mismatches for all fields.

Return type:

dict[str, Any]