Skip to content

Getting Started

Installation

pip install fushinryu-model

Requires Python 3.11 or later.

Core concepts in 60 seconds

The library models three nested entities:

  • A Scope groups related user stories under a named organisational unit.
  • A UserStory describes a requirement from the perspective of a role.
  • An AcceptanceCriterion states the testable condition that defines when the story is done.

Validation evidence — manual reviews or automated test results — is attached to acceptance criteria as immutable records.

Minimal example

from datetime import datetime, timezone
from fushinryu_model import (
    AcceptanceCriterion,
    ManualValidation,
    Scope,
    UserStory,
    UserStoryType,
)

# 1. Define an acceptance criterion
ac = AcceptanceCriterion(
    id=1,
    given="a valid request is sent",
    when="the endpoint is called",
    then="the system returns HTTP 200",
)

# 2. Attach a manual validation record
validation = ManualValidation(
    verdict="tested against staging; response was 200 OK",
    passed=True,
    timestamp=datetime.now(timezone.utc),
)
ac = ac.model_copy(update={"validations": frozenset([validation])})

# 3. Build a user story with the criterion
story = UserStory(
    id=1,
    who="API consumer",
    what="a successful health-check response",
    why="I can confirm the service is available",
    type=UserStoryType.FUNCTIONAL,
    acceptance_criteria=frozenset([ac]),
)

# 4. Wrap it in a scope
scope = Scope(
    id="my_service",
    name="My Service",
    description="Requirements for my service.",
    user_stories=frozenset([story]),
)

# 5. Check fulfilment
print(ac.is_validated)    # True
print(story.is_validated) # True

Next steps

  • Read the Domain Model page for a full picture of how entities relate.
  • See Merging to understand how parent and child scopes combine.
  • Browse the Reference for complete API documentation.