remote

Labs

Description

Load a model from a SysML v2 API and Services server, change it, and push the changes back.

Experimental: this API may change in any release, minor releases included.

A script written for local files runs against a server by changing only its load call: syside.load_model([path]) becomes syside.experimental.remote.load_model([url]), where url names a project, a branch or a commit on the server. push_model() saves the changes back as a commit. try_load_remote_model() and try_push_model() return a Result instead of raising.

Index

Classes

BasicCallback

HTTP Basic with username and password(), called as BearerCallback is.

BearerCallback

Authorization: Bearer <token()> on every request, token called once per request.

Err

A failed result of a try_ entrypoint.

Ok

A successful result of a try_ entrypoint.

RemoteError

Raised by the raising entrypoints; carries the RemoteFailure.

RemoteFailure

One failed remote operation.

ServerUrl

The base URL of a model server, with a scheme its host may be reached by.

ChangeSet

The element ids one push created, updated and deleted.

RemoteModel

A model loaded from a model server, with what a later push needs.

RemoteState

What a push of a loaded model needs, kept for as long as the model lives.

BranchInfo

A branch as listed by GET /projects/{p}/branches; head is its newest commit, None if the branch has no commit (head null or absent).

CommitInfo

A commit as listed by GET /projects/{p}/commits.

ProjectInfo

A project as listed by GET /projects.

Session

A connection to one model server.

TagInfo

A tag as listed by GET /projects/{p}/tags.

FromBranch

Diverge a new branch from the current head of an existing branch.

FromCommit

Diverge a new branch from an existing commit.

AuthPolicy

How to authenticate against indexes. Build one with the static constructors; the default for every call is none().

Functions

try_load_remote_model

Load a project’s model from the server; failures are returned, not raised.

load_model

Load a SysML v2 model from files, or from a model server.

load_model_unlocked

Load a SysML v2 model from files, or from a model server, without locking its documents.

try_load_model

Load a SysML v2 model from files, or from a model server, keeping models with errors.

try_load_model_unlocked

Load a SysML v2 model from files, or from a model server, without locking its documents, keeping models with errors.

remote_state

The state of model if it was loaded from a model server, else None.

create_branch

try_create_branch(), raising on failure.

push_model

try_push_model(), raising on failure.

try_create_branch

Create the branch name of project starting at base.

try_push_model

Push the changes of model since it was loaded or last pushed, as one commit on branch.

Enumerations

FailureKind

The class of a remote failure.


Functions

try_load_remote_model(session: syside.experimental.remote.Session, project: syside.experimental.remote.ProjectId, *, commit: syside.experimental.remote.CommitId, branch: None = ...) → syside.experimental.remote.Result[syside.experimental.remote.RemoteModel]

Load a project’s model from the server; failures are returned, not raised.

With neither commit nor branch the project’s default branch is loaded. A branch that is a str is a branch name. Err(NOT_FOUND) if the project, branch or commit does not exist; Err(MALFORMED_RESPONSE) if the server’s JSON is rejected, including by the core.

An empty state loads: a branch without a commit (base is None, no elements are requested), or a commit without elements (base is that commit; a commit given here is then requested itself, so that an unknown one is NOT_FOUND on a server that lists no elements for it). The model then has one user document with an empty root namespace, so new elements can be built into it, and baseline is {}; see RemoteModel.unsaved_root for how the first save creates that root.

The model’s references into the standard library resolve to the core’s own library, which the project does not hold. Stubs of library elements, which a server that keeps only references within the project needs (see library_stubs on Session), are dropped. A reference to a library element the core lacks is Err(MALFORMED_RESPONSE), as is any reference the core cannot resolve.

Raises:

ValueError – If both commit and branch are given (a programming error).

try_load_remote_model(session: syside.experimental.remote.Session, project: syside.experimental.remote.ProjectId, *, commit: None = ..., branch: syside.experimental.remote.BranchId | str | None = ...) → syside.experimental.remote.Result[syside.experimental.remote.RemoteModel]
load_model(paths: syside.PathLike | Iterable[syside.PathLike | syside.Source] | None = ..., environment: syside.Environment | None = ..., warnings_as_errors: bool = ..., attach_comments: bool = ..., config: syside.Discoverable = ..., sysand_dir: syside.Discoverable = ..., *, auth: syside.experimental.remote.Credentials | None = ..., session: syside.experimental.remote.Session | None = ..., **kwargs: Never) → syside.Model

Load a SysML v2 model from files, or from a model server.

Without a model-server URL in paths, this is the core’s load_model; see there for the parameters other than auth and session.

A model-server URL is https:// (or http:// to a loopback host) followed by the API’s resource path of a project (its default branch), a branch, or a commit:

model = load_model(["https://host/api/projects/<projectId>/branches/<branchId>"])

A branch may also be named by its name, percent-encoded (.../branches/feature%2Fx); a segment in the API’s id form (8-4-4-4-12 hex digits) is an id.

It must be the only path, and environment, warnings_as_errors, attach_comments, config and sysand_dir must keep their defaults. auth supplies credentials as for Session; None reads the SYSAND_CRED_* environment variables and never opens the OS credential store. Without session the load opens a session to the URL’s server and closes it after. With session the load runs on it, with its credentials and options, and leaves it open; its server must be the URL’s.

Raises:
  • ModelError – As the core’s load_model, for files.

  • RemoteError – If loading from the server fails; try_load_remote_model() returns the failure instead.

  • ValueError – If a URL is not the only path, is not one of the forms above, or is given with an option above; if auth or session is given without a URL, or both are given; or if session is for another server.

load_model_unlocked(paths: syside.PathLike | Iterable[syside.PathLike | syside.Source] | None = ..., environment: syside.Environment | None = ..., warnings_as_errors: bool = ..., attach_comments: bool = ..., config: syside.Discoverable = ..., sysand_dir: syside.Discoverable = ..., *, auth: syside.experimental.remote.Credentials | None = ..., session: syside.experimental.remote.Session | None = ..., **kwargs: Never) → syside.UnlockedModel

Load a SysML v2 model from files, or from a model server, without locking its documents.

Without a model-server URL in paths, this is the core’s load_model_unlocked. A URL is accepted as by load_model(). The model that lock() returns can be pushed with push_model(), each time it is locked.

Raises:
try_load_model(paths: syside.PathLike | Iterable[syside.PathLike | syside.Source] | None = ..., environment: syside.Environment | None = ..., attach_comments: bool = ..., config: syside.Discoverable = ..., sysand_dir: syside.Discoverable = ..., *, auth: syside.experimental.remote.Credentials | None = ..., session: syside.experimental.remote.Session | None = ..., **kwargs: Never) → syside.Model

Load a SysML v2 model from files, or from a model server, keeping models with errors.

Without a model-server URL in paths, this is the core’s try_load_model. A URL is accepted as by load_model(). As the core raises when a path does not exist, a failure to read the server raises; try_load_remote_model() returns it instead.

Raises:
try_load_model_unlocked(paths: syside.PathLike | Iterable[syside.PathLike | syside.Source] | None = ..., environment: syside.Environment | None = ..., attach_comments: bool = ..., config: syside.Discoverable = ..., sysand_dir: syside.Discoverable = ..., *, auth: syside.experimental.remote.Credentials | None = ..., session: syside.experimental.remote.Session | None = ..., **kwargs: Never) → syside.UnlockedModel

Load a SysML v2 model from files, or from a model server, without locking its documents, keeping models with errors.

Without a model-server URL in paths, this is the core’s try_load_model_unlocked. A URL is accepted as by load_model(), and a failure to read the server raises, as for try_load_model(). The model that lock() returns can be pushed with push_model(), each time it is locked.

Raises:
remote_state(model: syside.Model) → syside.experimental.remote.RemoteState | None

The state of model if it was loaded from a model server, else None.

The state follows the model through unlock() and lock(): the model that lock() returns has it, and the model that was unlocked has none.

create_branch(session: syside.experimental.remote.Session, project: syside.experimental.remote.ProjectId, *, name: str, base: syside.experimental.remote.BranchBase) → syside.experimental.remote.BranchId

try_create_branch(), raising on failure.

Raises:

RemoteError – With the failure of the Err.

push_model(model: syside.Model, *, branch: syside.experimental.remote.BranchId | None = ..., description: str | None = ..., verify: bool = ..., repair: bool = ..., auth: syside.experimental.remote.Credentials | None = ..., session: syside.experimental.remote.Session | None = ..., changed: Iterable[syside.Element] | None = ...) → syside.experimental.remote.CommitId | None

try_push_model(), raising on failure.

Raises:
try_create_branch(session: syside.experimental.remote.Session, project: syside.experimental.remote.ProjectId, *, name: str, base: syside.experimental.remote.BranchBase) → syside.experimental.remote.Result[syside.experimental.remote.BranchId]

Create the branch name of project starting at base.

The base is resolved first (a missing branch or commit is NOT_FOUND). A branch of that name that is not deleted fails with ALREADY_EXISTS and is never moved; an HTTP 409 from the POST maps to the same kind. The POST is never retried. The name is checked by a GET one request before the POST, so a branch of that name created in between is detected only if the server refuses the POST with 409; a server that does not leaves two branches of that name.

try_push_model(model: syside.Model, *, branch: syside.experimental.remote.BranchId | None = ..., description: str | None = ..., verify: bool = ..., repair: bool = ..., auth: syside.experimental.remote.Credentials | None = ..., session: syside.experimental.remote.Session | None = ..., changed: Iterable[syside.Element] | None = ...) → syside.experimental.remote.Result[syside.experimental.remote.CommitId | None]

Push the changes of model since it was loaded or last pushed, as one commit on branch.

model must have been loaded from a model server: load_model() with a server URL, or RemoteModel.model from try_load_remote_model() (pass the model attribute, not the RemoteModel); its RemoteModel fields are read and updated through the model alone. Without session the push connects to the server the model was loaded from, with auth if given, else the credentials of the load, and closes the connection after.

branch defaults to the branch the model was loaded from. The branch must exist: it is looked up first (GET, NOT_FOUND on a missing branch) and never created; the lookup is made even when nothing changed. When the change set is empty no commit is made and base is returned unchanged, which is None for a model of a branch that has no commit and no content yet.

A model loaded from an empty state has a synthesized root namespace the server lacks (unsaved_root); the first push with any content creates it in the same commit, and clears the marker.

Otherwise exactly one POST is issued, never retried. The commit body has no previousCommit: the normative CommitRequest schema has no such property and forbids unknown ones (additionalProperties: false), although the PIM’s create_commit takes previous commits. Neither tested server would act on it: the OMG reference server accepts a single {"@id"} object but uses the branch head instead (500 on an array or an unknown id), and Flexo accepts it and records no previous commit. So the server appends the commit to whatever the head of branch is. The change set is relative to base, so the push is refused with BRANCH_MOVED, before any POST, unless the branch’s head is base (no head at all if base is None): another commit on the branch since the load, or a branch that diverged elsewhere, would otherwise receive changes computed against a different state. The check precedes the POST by one request, so a commit made in between is not detected.

With verify the stored change set is compared to the submission; with repair missing entries are re-submitted in one follow-up commit and its id is returned.

By default the whole model is serialized and compared with baseline, which finds every change and takes time in proportion to the model. changed names the elements that changed instead; only their scopes are serialized and compared, and the rest of the model is taken as unchanged, so the time is in proportion to what is named. The scope of an element is the element, everything it owns, and its owning relationship (a rename changes the membership’s name too). Name:

  • an element whose properties changed (renamed, made abstract, a value set): the element;

  • an element added: its owner (an added element named alone widens to its nearest ancestor that baseline has, which is its owner unless that is new too);

  • an element removed: its former owner, or any ancestor; a removed element itself is refused;

  • an element moved: its old and its new owner.

A change outside every named scope is not pushed, and verify does not notice its absence, since the server stores what was sent. An element moved from an unnamed owner into a named scope is submitted as created there while the unnamed owner still lists it. changed=[] compares nothing and makes no commit. For a model loaded from an empty state (unsaved_root set) changed is ignored and the whole model is compared, so that the root is created with the first content.

With a session that has library_stubs (Session), the session given, or else the one the model was loaded with, the commit also holds a stub for each standard library element it refers to that the branch does not hold, so that a server that keeps only references to elements of the project keeps them. Stubs are part of the commit and of what verify compares, but not of baseline or last_change_set. load_model() with a server URL and no session loads without the option, so to push its model to such a server, load or push with a session that has it.

On success base is the returned commit, baseline the serialization that was submitted and last_change_set the submitted change set. If the commit was made but verification or repair failed, the commit exists on the server, so base becomes it, while baseline and last_change_set stay as they were: the next push resubmits every difference to the old baseline, which restores entries the server lacks. If the POST itself fails, the fields are unchanged. A failure after the request reached the server (read timeout, 5xx, a broken connection, an unreadable response) may follow a commit that was made; its message says so, and the next push is then BRANCH_MOVED. The same holds for the repair POST.

Raises:
  • ValueError – If model has been unlocked (push the model that lock() returns, which keeps the remote state); if model was not loaded from a model server; if no branch is given and the model was not loaded by branch; if repair is set without verify; if both session and auth are given; if session is for another server; or if changed names an element that is not part of model (another model, the standard library, or an element removed from its owner); or if the core serializes two elements of model with one id (a core defect, seen with the parameter of a select expression built in this process), which would lose one of them; or, with library_stubs, if the commit refers to an element that neither the model nor the branch holds and that is not a standard library element the model relates to (with changed, also an element new outside every named scope), since the server would lose the reference. No request is made after the branch-head check.

  • TypeError – If changed is a single element or a string, not a collection.

Enumerations

class FailureKind

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.

The class of a remote failure.