Skip to content

Add type-safe Jira issue models with fluent builders#1

Merged
yechielb2000 merged 1 commit intomasterfrom
feat/type-safe-jira-models
Apr 12, 2026
Merged

Add type-safe Jira issue models with fluent builders#1
yechielb2000 merged 1 commit intomasterfrom
feat/type-safe-jira-models

Conversation

@yechielb2000
Copy link
Copy Markdown
Owner

Summary

  • Introduces a new atlassian.models.jira package that replaces manual JSON/dictionary construction with typed dataclasses, fluent builders, and a centralized serializer for all Jira issue operations.
  • Covers the full lifecycle: create (IssueBuilder + serialize), update (UpdateBuilder), transition (TransitionBuilder), comment (Comment model), and deserialize (from_dict on all value objects).
  • Includes 86 pytest tests, a py.typed PEP 561 marker, and a convenience import alias (atlassian.jira_models).

New modules

Module Purpose
fields.py Frozen value-object dataclasses (Project, Priority, User, etc.) with to_dict()/from_dict()
issues.py JiraIssue base + Task/Bug/Story/Epic/SubTask with __init_subclass__ auto-registry
builders.py Generic IssueBuilder[T] with per-type builders, ADF bridge, .validate() chaining
serializer.py FieldMapping + serialize()/to_fields_dict()/bulk_serialize()
adf.py ADFBuilder for Atlassian Document Format rich-text descriptions
validation.py Pre-flight validate()/validate_or_raise()
update.py UpdateBuilder for issue_update with set/add/remove operations
transition.py Transition model for set_issue_status()
comment.py Comment + Visibility for issue_add_comment()

Quick usage example

from atlassian.models.jira import bug, serialize

payload = (
    bug()
    .project("PROJ")
    .summary("Login button broken on Safari")
    .priority("High")
    .labels("safari", "regression")
    .description(lambda d: d.paragraph("Steps to reproduce..."))
    .build_payload()
)

jira.create_issue(fields=payload["fields"])

Test plan

  • All 86 unit tests pass (pytest tests/test_jira_models.py -v)
  • Manual review of public API surface and docstrings
  • Verify import paths work from consumer code

Introduce a new `atlassian.models.jira` package that eliminates manual
JSON/dictionary construction for Jira operations in favor of typed
dataclasses, fluent builders, and a centralized serializer.

Core modules:
- fields.py: frozen value-object dataclasses (Project, Priority, User, etc.)
  with to_dict()/from_dict() for (de)serialization
- issues.py: JiraIssue base + Task/Bug/Story/Epic/SubTask with
  __init_subclass__ auto-registry
- builders.py: generic IssueBuilder[T] with per-type builders, ADF bridge
  pattern, and .validate() chaining
- serializer.py: FieldMapping + serialize()/to_fields_dict()/bulk_serialize()
- adf.py: ADFBuilder for Atlassian Document Format rich-text descriptions
- validation.py: pre-flight validate()/validate_or_raise()
- update.py: UpdateBuilder for issue_update with set/add/remove operations
- transition.py: Transition model for set_issue_status()
- comment.py: Comment + Visibility for issue_add_comment()

Also adds py.typed marker, convenience import alias (atlassian.jira_models),
and 86 tests covering all modules.
@yechielb2000 yechielb2000 merged commit c2cdc49 into master Apr 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant