behave-model 1.0.0__py3-none-any.whl

behave_model/__init__.py

@@ -0,0 +1,164 @@
+"""behave-model — Canonical object model for Behave projects.
+
+Public API:
+
+    from behave_model import (
+        load_project,
+        load_feature,
+        Project,
+        Feature,
+        Scenario,
+        ScenarioOutline,
+        Step,
+        Table,
+        Tag,
+        Background,
+        Examples,
+        DocString,
+        Comment,
+        Location,
+        Metadata,
+        Visitor,
+        Validator,
+        DictSerializer,
+        JsonSerializer,
+        PrettyPrinter,
+    )
+
+    project = load_project("features/")
+    print(project.statistics())
+"""
+
+from behave_model.exceptions import (
+    BehaveModelError,
+    ParseError,
+    SerializationError,
+    TransformationError,
+    ValidationError,
+)
+from behave_model.model import (
+    Background,
+    Comment,
+    DocString,
+    Examples,
+    Feature,
+    Location,
+    Metadata,
+    Project,
+    Rule,
+    Scenario,
+    ScenarioOutline,
+    Step,
+    Table,
+    TableRow,
+    Tag,
+)
+from behave_model.parser import (
+    BehaveParserAdapter,
+    load_feature,
+    load_project,
+    parse_feature,
+    parse_project,
+)
+from behave_model.queries import (
+    find_feature,
+    find_features_with_tag,
+    find_outlines,
+    find_plain_scenarios,
+    find_scenarios,
+    find_scenarios_with_tag,
+    find_steps,
+    find_tag,
+)
+from behave_model.serializers import DictSerializer, JsonSerializer, PrettyPrinter
+from behave_model.transformations import (
+    add_tag_to_feature,
+    normalize_whitespace,
+    remove_tag,
+    rename_scenario,
+    rename_tag,
+    sort_features,
+    sort_scenarios,
+    sort_tags,
+)
+from behave_model.validation import (
+    DuplicateFeatureNamesRule,
+    DuplicateScenarioNamesRule,
+    EmptyFeatureRule,
+    EmptyScenarioRule,
+    InvalidTableRule,
+    ValidationIssue,
+    ValidationRule,
+    Validator,
+)
+from behave_model.visitors import CollectingVisitor, CountingVisitor, Visitor
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # model
+    "Background",
+    "Comment",
+    "DocString",
+    "Examples",
+    "Feature",
+    "Location",
+    "Metadata",
+    "Project",
+    "Rule",
+    "Scenario",
+    "ScenarioOutline",
+    "Step",
+    "Table",
+    "TableRow",
+    "Tag",
+    # parser
+    "BehaveParserAdapter",
+    "load_feature",
+    "load_project",
+    "parse_feature",
+    "parse_project",
+    # queries
+    "find_feature",
+    "find_features_with_tag",
+    "find_outlines",
+    "find_plain_scenarios",
+    "find_scenarios",
+    "find_scenarios_with_tag",
+    "find_steps",
+    "find_tag",
+    # visitors
+    "CollectingVisitor",
+    "CountingVisitor",
+    "Visitor",
+    # serializers
+    "DictSerializer",
+    "JsonSerializer",
+    "PrettyPrinter",
+    # transformations
+    "add_tag_to_feature",
+    "normalize_whitespace",
+    "remove_tag",
+    "rename_scenario",
+    "rename_tag",
+    "sort_features",
+    "sort_scenarios",
+    "sort_tags",
+    # validation
+    "DuplicateFeatureNamesRule",
+    "DuplicateScenarioNamesRule",
+    "EmptyFeatureRule",
+    "EmptyScenarioRule",
+    "InvalidTableRule",
+    "ValidationIssue",
+    "ValidationRule",
+    "Validator",
+    # exceptions
+    "BehaveModelError",
+    "ParseError",
+    "SerializationError",
+    "TransformationError",
+    "ValidationError",
+    # version
+    "__version__",
+]

behave_model/exceptions.py

@@ -0,0 +1,28 @@
+"""Exception hierarchy for behave-model."""
+
+from __future__ import annotations
+
+
+class BehaveModelError(Exception):
+    """Base exception for all behave-model errors."""
+
+
+class ParseError(BehaveModelError):
+    """Raised when a feature file cannot be parsed."""
+
+
+class ValidationError(BehaveModelError):
+    """Raised when a validation rule fails."""
+
+    def __init__(self, message: str, *, rule: str = "", location: str = "") -> None:
+        super().__init__(message)
+        self.rule = rule
+        self.location = location
+
+
+class TransformationError(BehaveModelError):
+    """Raised when a transformation cannot be applied."""
+
+
+class SerializationError(BehaveModelError):
+    """Raised when serialization fails."""

behave_model/model/__init__.py

@@ -0,0 +1,34 @@
+"""Domain model package — re-exports all model classes."""
+
+from behave_model.model.background import Background
+from behave_model.model.comment import Comment
+from behave_model.model.docstring import DocString
+from behave_model.model.examples import Examples
+from behave_model.model.feature import Feature
+from behave_model.model.location import Location
+from behave_model.model.metadata import Metadata
+from behave_model.model.project import Project
+from behave_model.model.rule import Rule
+from behave_model.model.scenario import Scenario
+from behave_model.model.scenario_outline import ScenarioOutline
+from behave_model.model.step import Step
+from behave_model.model.table import Table, TableRow
+from behave_model.model.tag import Tag
+
+__all__ = [
+    "Background",
+    "Comment",
+    "DocString",
+    "Examples",
+    "Feature",
+    "Location",
+    "Metadata",
+    "Project",
+    "Rule",
+    "Scenario",
+    "ScenarioOutline",
+    "Step",
+    "Table",
+    "TableRow",
+    "Tag",
+]

behave_model/model/background.py

@@ -0,0 +1,39 @@
+"""Background model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from behave_model.model.location import Location
+from behave_model.model.step import Step
+
+if TYPE_CHECKING:
+    from behave_model.visitors.visitor import Visitor
+
+
+@dataclass
+class Background:
+    """A Background block that runs before every scenario in a feature.
+
+    Attributes:
+        name: Optional background name.
+        steps: Steps that execute before each scenario.
+        location: Source location.
+    """
+
+    name: str = ""
+    steps: list[Step] = field(default_factory=list)
+    location: Location = field(default_factory=Location)
+
+    def __iter__(self):
+        return iter(self.steps)
+
+    def __len__(self) -> int:
+        return len(self.steps)
+
+    def accept(self, visitor: "Visitor") -> None:
+        """Accept a visitor."""
+        visitor.visit_background(self)
+        for step in self.steps:
+            step.accept(visitor)

behave_model/model/comment.py

@@ -0,0 +1,23 @@
+"""Comment model preserving source-file comments."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from behave_model.model.location import Location
+
+
+@dataclass
+class Comment:
+    """A comment extracted from a feature file.
+
+    Attributes:
+        text: The raw comment text including the ``#`` prefix.
+        location: Source location of the comment.
+    """
+
+    text: str
+    location: Location = Location()
+
+    def __str__(self) -> str:
+        return self.text

behave_model/model/docstring.py

@@ -0,0 +1,29 @@
+"""DocString (multi-line text) model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from behave_model.model.location import Location
+
+
+@dataclass
+class DocString:
+    """A docstring attached to a step.
+
+    Attributes:
+        content: The raw text content.
+        content_type: Optional content-type hint (e.g. ``json``, ``xml``).
+        delimiter: The delimiter used (``\"\"\"`` or `````).
+        location: Source location.
+    """
+
+    content: str = ""
+    content_type: str = ""
+    delimiter: str = '"""'
+    location: Location = field(default_factory=Location)
+
+    @property
+    def lines(self) -> list[str]:
+        """Return the content split into lines."""
+        return self.content.splitlines()

behave_model/model/examples.py

@@ -0,0 +1,44 @@
+"""Examples model for scenario outlines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from behave_model.model.location import Location
+from behave_model.model.table import Table
+from behave_model.model.tag import Tag
+
+if TYPE_CHECKING:
+    from behave_model.visitors.visitor import Visitor
+
+
+@dataclass
+class Examples:
+    """An Examples table attached to a ScenarioOutline.
+
+    Attributes:
+        name: Optional name for the examples block.
+        tags: Tags on the examples block.
+        table: The data table containing headers and rows.
+        location: Source location.
+    """
+
+    name: str = ""
+    tags: list[Tag] = field(default_factory=list)
+    table: Table = field(default_factory=Table)
+    location: Location = field(default_factory=Location)
+
+    @property
+    def headers(self) -> list[str]:
+        """Column headers from the underlying table."""
+        return self.table.headers
+
+    @property
+    def rows(self) -> list:
+        """Data rows from the underlying table."""
+        return self.table.rows
+
+    def accept(self, visitor: "Visitor") -> None:
+        """Accept a visitor."""
+        visitor.visit_examples(self)

behave_model/model/feature.py

@@ -0,0 +1,113 @@
+"""Feature model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterator, Union
+from typing import TYPE_CHECKING
+
+from behave_model.model.background import Background
+from behave_model.model.comment import Comment
+from behave_model.model.location import Location
+from behave_model.model.rule import Rule
+from behave_model.model.scenario import Scenario
+from behave_model.model.scenario_outline import ScenarioOutline
+from behave_model.model.tag import Tag
+
+if TYPE_CHECKING:
+    from behave_model.visitors.visitor import Visitor
+
+# Union type for any scenario-like element
+ScenarioLike = Union[Scenario, ScenarioOutline]
+
+
+@dataclass
+class Feature:
+    """A feature parsed from a ``.feature`` file.
+
+    Attributes:
+        name: Feature name.
+        description: Optional description text (multi-line).
+        tags: Tags applied at the feature level.
+        background: Optional Background block (feature-level).
+        scenarios: List of Scenario and ScenarioOutline objects directly
+            under the feature (not inside a Rule).
+        rules: List of Rule blocks (Gherkin v6).
+        comments: Comments associated with the feature.
+        location: Source location.
+        language: Feature file language (default ``en``).
+    """
+
+    name: str = ""
+    description: str = ""
+    tags: list[Tag] = field(default_factory=list)
+    background: Background | None = None
+    scenarios: list[ScenarioLike] = field(default_factory=list)
+    rules: list[Rule] = field(default_factory=list)
+    comments: list[Comment] = field(default_factory=list)
+    location: Location = field(default_factory=Location)
+    language: str = "en"
+
+    def __iter__(self) -> Iterator[ScenarioLike]:
+        return iter(self.scenarios)
+
+    def __len__(self) -> int:
+        return len(self.scenarios)
+
+    @property
+    def tag_names(self) -> list[str]:
+        """Return tag names as strings."""
+        return [t.name for t in self.tags]
+
+    def has_tag(self, name: str) -> bool:
+        """Check whether the feature has a given tag."""
+        return any(t.name == name for t in self.tags)
+
+    def outlines(self) -> list[ScenarioOutline]:
+        """Return only scenario outlines."""
+        return [s for s in self.scenarios if isinstance(s, ScenarioOutline)]
+
+    def plain_scenarios(self) -> list[Scenario]:
+        """Return only plain (non-outline) scenarios."""
+        return [s for s in self.scenarios if isinstance(s, Scenario)]
+
+    def all_scenarios(self) -> list[ScenarioLike]:
+        """Return all scenario-like elements (including those inside rules)."""
+        result = list(self.scenarios)
+        for rule in self.rules:
+            result.extend(rule.scenarios)
+        return result
+
+    def all_tags(self) -> list[Tag]:
+        """Return all tags (feature + rule + scenario tags)."""
+        tags = list(self.tags)
+        for s in self.scenarios:
+            tags.extend(s.tags)
+        for rule in self.rules:
+            tags.extend(rule.tags)
+            for s in rule.scenarios:
+                tags.extend(s.tags)
+        return tags
+
+    def all_steps(self):
+        """Return every step in the feature (background + scenarios + rules)."""
+        from behave_model.model.step import Step
+
+        steps: list[Step] = []
+        if self.background:
+            steps.extend(self.background.steps)
+        for s in self.scenarios:
+            steps.extend(s.steps)
+        for rule in self.rules:
+            steps.extend(rule.all_steps())
+        return steps
+
+    def accept(self, visitor: "Visitor") -> None:
+        """Accept a visitor."""
+        visitor.visit_feature(self)
+        if self.background:
+            self.background.accept(visitor)
+        for s in self.scenarios:
+            s.accept(visitor)
+        for rule in self.rules:
+            rule.accept(visitor)

behave_model/model/location.py

@@ -0,0 +1,30 @@
+"""Location model representing a position in a source file."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Location:
+    """Represents a position in a feature file.
+
+    Attributes:
+        filename: Path to the source file.
+        line: 1-based line number.
+        column: 1-based column number (0 if unknown).
+    """
+
+    filename: str = ""
+    line: int = 0
+    column: int = 0
+
+    def __str__(self) -> str:
+        parts: list[str] = []
+        if self.filename:
+            parts.append(self.filename)
+        if self.line:
+            parts.append(f"line {self.line}")
+        if self.column:
+            parts.append(f"column {self.column}")
+        return ", ".join(parts) if parts else "<unknown>"

behave_model/model/metadata.py

@@ -0,0 +1,23 @@
+"""Metadata model for project-level information."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Metadata:
+    """Project-level metadata.
+
+    Attributes:
+        created_at: When the project model was created.
+        source_path: Root path from which the project was loaded.
+        tool_version: Version of behave-model that produced this metadata.
+        extra: Free-form key-value pairs for extensions.
+    """
+
+    created_at: datetime = field(default_factory=datetime.now)
+    source_path: str = ""
+    tool_version: str = "0.1.0"
+    extra: dict[str, str] = field(default_factory=dict)