reqif Labs

Syside Automator ReqIF import/export.

This module converts between ReqIF (Requirements Interchange Format) files and SysMLv2 workspaces. It can be driven from the command line or from Python scripts; both surfaces share the same underlying entry points.

Installation

The public functions and CLI both require the [reqif] extra which pulls in additional third-party dependencies. Install it with:

pip install 'syside[reqif]'
# or, for uv-managed projects:
uv add 'syside[reqif]'

When the extra is missing, the captured ImportError is exposed as _missing_extra_error for callers building their own CLI.

Command-line usage

The CLI is reachable both through the top-level syside console script and as a runnable module. The three are equivalent:

syside reqif <subcommand> [options]
python -m syside reqif <subcommand> [options]
python -m syside.reqif <subcommand> [options]

All subcommands operate on the current working directory as the workspace root. The available subcommands are:

  • init — write the canonical SysideReqIF SysMLv2 library into the workspace so subsequent imports have something to reference. Use --lib-dir to override the default LIBRARY_DIR location.

  • import <file> — convert a .reqif or .reqifz file into SysMLv2 packages under the workspace, performing a fresh build or a delta update depending on existing content. Attachments are extracted into --attachments-dir (default: ATTACHMENTS_DIR).

  • lock — assign stable UUIDs and last-change timestamps to any ReqIF-tagged elements that don’t yet have them, so subsequent round-trips preserve identity. Takes no options.

  • export — convert the SysMLv2 models from the workspace into a .reqif or .reqifz file.

  • check reqif <file> — validate that a ReqIF file satisfies the invariants required for round-trippable conversion (relation-group ownership, no hierarchy cycles, no name shadowing, etc.).

  • check sysml — validate the workspace SysMLv2 model (currently enforces at most one top-level package per .sysml document, and that all ReqIF tags are locked).

Each subcommand exits 0 on success and raises on failure.

Library usage

Every CLI subcommand has a public Python counterpart: an options dataclass plus a function named after the subcommand. The functions return the CLI exit code and raise ValueError on validation failures, and operate on the current working directory (use os.chdir to target a different workspace).

from pathlib import Path

from syside.reqif import (
    ImportOptions,
    CheckReqifOptions,
    InitOptions,
    check_reqif,
    import_,
    init,
)

# Initialise the workspace once.
init(InitOptions(lib_dir=None))

# Validate a ReqIF file before importing it.
reqif_file = Path("requirements.reqif")
check_reqif(CheckReqifOptions(file=reqif_file))

# Import the file; attachments land in ./attachments_reqif/.
import_(ImportOptions(file=reqif_file, attachments_dir=None))

The default-path constants (LIBRARY_PKG, LIBRARY_DIR, ATTACHMENTS_DIR) are re-exported here so callers can reference the same defaults the CLI uses without reaching into private modules.

Index

Classes

CheckReqifOptions

Parsed arguments for the syside reqif check reqif subcommand.

CheckSysmlOptions

Parsed arguments for the syside reqif check sysml subcommand.

ExportOptions

Parsed arguments for the syside reqif export subcommand.

ImportOptions

Parsed arguments for the syside reqif import subcommand.

InitOptions

Parsed arguments for the syside reqif init subcommand.

OptionsBase

Mixin for subcommand option dataclasses.
Attributes

ATTACHMENTS_DIR

R

LIBRARY_DIR

R

LIBRARY_PKG

R
Functions

check_reqif

Run the ReqIF-side validation suite against opts.file.

check_sysml

Run the SysMLv2-side validation suite against the current workspace.

export

Run the SysMLv2 -> ReqIF conversion.

import_

Run the ReqIF -> SysMLv2 conversion.

init

Initialise the current workspace for ReqIF <-> SysMLv2 conversion.

lock

Lock unlocked ReqIF-tagged elements in the workspace SysMLv2 model.

Attributes

ATTACHMENTS_DIR = 'attachments_reqif'

Default workspace-relative directory that syside reqif import extracts ReqIF attachments into when ImportOptions.attachments_dir is unset.

LIBRARY_DIR = 'lib'

Default workspace-relative directory for the SysMLv2 ReqIF library, used by syside reqif init when InitOptions.lib_dir is unset.

LIBRARY_PKG = 'SysideReqIF'

Name (without .sysml extension) of the canonical SysMLv2 library package that syside reqif init writes into the workspace.

󰊕 Functions

check_reqif(opts: syside.reqif.CheckReqifOptions) → int

Run the ReqIF-side validation suite against opts.file.

Loads the file into the intermediate representation runs the same validations as when doing run_import.

Returns 0 on success; raises ValueError on the first failed check.

check_sysml(opts: syside.reqif.CheckSysmlOptions) → int

Run the SysMLv2-side validation suite against the current workspace.

Loads every .sysml document under the current working directory and runs the same validations as when doing run_export.

Returns 0 on success; raises ValueError on the first failed check.

export(opts: syside.reqif.ExportOptions) → int

Run the SysMLv2 -> ReqIF conversion.

Loads the workspace SysMLv2 model under the current working directory and converts it into ReqIF saved into opts.file. If the opts.reqifz flag is set, the resulting ReqIF file is zipped into a .reqifz file, along with all files found in opts.attachments_dir (or <cwd>/ joined with syside.reqif.ATTACHMENTS_DIR when unset) recursively.

  • opts.title is used as the title for the ReqIF file and is required.

  • opts.comment is used as the comment for the ReqIF file.

  • opts.repository_id is used as the repository ID for the ReqIF file.

The latter two are optional.

Returns 0 on success.

import_(opts: syside.reqif.ImportOptions) → int

Run the ReqIF -> SysMLv2 conversion.

Loads the workspace SysMLv2 model under the current working directory and parses opts.file into the intermediate representation. If the workspace contains no existing ReqIF content, a fresh set of SysMLv2 packages is built from the IR; otherwise a delta import is performed against the existing content.

Attachments referenced by the ReqIF file are extracted into opts.attachments_dir (or <cwd>/ joined with syside.reqif.ATTACHMENTS_DIR when unset).

Returns 0 on success.

init(opts: syside.reqif.InitOptions) → int

Initialise the current workspace for ReqIF <-> SysMLv2 conversion.

Scans the current working directory for an existing <{LIBRARY_PKG}>.sysml file (where LIBRARY_PKG is syside.reqif.LIBRARY_PKG), normalising any BOM and CRLF/CR line endings before comparison so a Windows checkout is not mistaken for a stale copy. If the canonical library content is already present nothing happens; otherwise the canonical SysMLv2 ReqIF library is written under opts.lib_dir (or syside.reqif.LIBRARY_DIR when unset).

Raises ValueError if more than one <{LIBRARY_PKG}>.sysml is found in the workspace, since a “first hit wins” rewrite would silently leave the other copies stale.

Returns 0 on success.

lock() → int

Lock unlocked ReqIF-tagged elements in the workspace SysMLv2 model.

Walks the model for elements carrying the ReqIF tag whose identifier or last-change fields have not yet been populated, generates fresh UUIDs and timestamps, and writes them back so subsequent ReqIF round-trips have stable identities.

Unlike the other entry points this function takes no options — it always operates on the workspace under the current working directory.

Returns 0 on success.