remote
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
HTTP Basic with |
||
|
||
A failed result of a |
||
A successful result of a |
||
Raised by the raising entrypoints; carries the |
||
One failed remote operation. |
||
The base URL of a model server, with a scheme its host may be reached by. |
||
The element ids one push created, updated and deleted. |
||
A model loaded from a model server, with what a later push needs. |
||
What a push of a loaded model needs, kept for as long as the model lives. |
||
A branch as listed by |
||
A commit as listed by |
||
A project as listed by |
||
A connection to one model server. |
||
A tag as listed by |
||
Diverge a new branch from the current head of an existing branch. |
||
Diverge a new branch from an existing commit. |
||
How to authenticate against indexes. Build one with the static
constructors; the default for every call is |
Functions
Load a project’s model from the server; failures are returned, not raised. |
||
Load a SysML v2 model from files, or from a model server. |
||
Load a SysML v2 model from files, or from a model server, without locking its documents. |
||
Load a SysML v2 model from files, or from a model server, keeping models with errors. |
||
Load a SysML v2 model from files, or from a model server, without locking its documents, keeping models with errors. |
||
The state of |
||
|
||
|
||
Create the branch |
||
Push the changes of |
Enumerations
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
commitnorbranchthe project’s default branch is loaded. Abranchthat is astris 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 (
baseisNone, no elements are requested), or a commit without elements (baseis that commit; acommitgiven here is then requested itself, so that an unknown one isNOT_FOUNDon 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, andbaselineis{}; seeRemoteModel.unsaved_rootfor 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_stubsonSession), are dropped. A reference to a library element the core lacks isErr(MALFORMED_RESPONSE), as is any reference the core cannot resolve.- Raises:
ValueError – If both
commitandbranchare 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’sload_model; see there for the parameters other thanauthandsession.A model-server URL is
https://(orhttp://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-12hex digits) is an id.It must be the only path, and
environment,warnings_as_errors,attach_comments,configandsysand_dirmust keep their defaults.authsupplies credentials as forSession;Nonereads theSYSAND_CRED_*environment variables and never opens the OS credential store. Withoutsessionthe load opens a session to the URL’s server and closes it after. Withsessionthe 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
authorsessionis given without a URL, or both are given; or ifsessionis 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’sload_model_unlocked. A URL is accepted as byload_model(). The model thatlock()returns can be pushed withpush_model(), each time it is locked.- Raises:
ModelError – As the core’s
load_model_unlocked, for files.RemoteError – If loading from the server fails.
ValueError – As
load_model().
- 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’stry_load_model. A URL is accepted as byload_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:
RemoteError – If loading from the server fails.
ValueError – As
load_model().
- 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’stry_load_model_unlocked. A URL is accepted as byload_model(), and a failure to read the server raises, as fortry_load_model(). The model thatlock()returns can be pushed withpush_model(), each time it is locked.- Raises:
RemoteError – If loading from the server fails.
ValueError – As
load_model().
- remote_state(model: syside.Model) syside.experimental.remote.RemoteState | None
The state of
modelif it was loaded from a model server, elseNone.The state follows the model through
unlock()andlock(): the model thatlock()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:
RemoteError – With the failure of the
Err.ValueError – As
try_push_model().
- 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
nameofprojectstarting atbase.The base is resolved first (a missing branch or commit is
NOT_FOUND). A branch of that name that is not deleted fails withALREADY_EXISTSand is never moved; an HTTP 409 from thePOSTmaps to the same kind. ThePOSTis never retried. The name is checked by aGETone request before thePOST, so a branch of that name created in between is detected only if the server refuses thePOSTwith 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
modelsince it was loaded or last pushed, as one commit onbranch.modelmust have been loaded from a model server:load_model()with a server URL, orRemoteModel.modelfromtry_load_remote_model()(pass themodelattribute, not theRemoteModel); itsRemoteModelfields are read and updated through the model alone. Withoutsessionthe push connects to the server the model was loaded from, withauthif given, else the credentials of the load, and closes the connection after.branchdefaults to the branch the model was loaded from. The branch must exist: it is looked up first (GET,NOT_FOUNDon a missing branch) and never created; the lookup is made even when nothing changed. When the change set is empty no commit is made andbaseis returned unchanged, which isNonefor 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
POSTis issued, never retried. The commit body has nopreviousCommit: the normativeCommitRequestschema has no such property and forbids unknown ones (additionalProperties: false), although the PIM’screate_committakes 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 ofbranchis. The change set is relative tobase, so the push is refused withBRANCH_MOVED, before anyPOST, unless the branch’s head isbase(no head at all ifbaseisNone): 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 thePOSTby one request, so a commit made in between is not detected.With
verifythe stored change set is compared to the submission; withrepairmissing 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.changednames 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
baselinehas, 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
verifydoes 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_rootset)changedis 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 whatverifycompares, but not ofbaselineorlast_change_set.load_model()with a server URL and nosessionloads without the option, so to push its model to such a server, load or push with asessionthat has it.On success
baseis the returned commit,baselinethe serialization that was submitted andlast_change_setthe submitted change set. If the commit was made but verification or repair failed, the commit exists on the server, sobasebecomes it, whilebaselineandlast_change_setstay as they were: the next push resubmits every difference to the old baseline, which restores entries the server lacks. If thePOSTitself 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 thenBRANCH_MOVED. The same holds for the repairPOST.- Raises:
ValueError – If
modelhas been unlocked (push the model thatlock()returns, which keeps the remote state); ifmodelwas not loaded from a model server; if no branch is given and the model was not loaded by branch; ifrepairis set withoutverify; if bothsessionandauthare given; ifsessionis for another server; or ifchangednames an element that is not part ofmodel(another model, the standard library, or an element removed from its owner); or if the core serializes two elements ofmodelwith one id (a core defect, seen with the parameter of a select expression built in this process), which would lose one of them; or, withlibrary_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 (withchanged, 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
changedis a single element or a string, not a collection.
Enumerations
- class FailureKind
The class of a remote failure.
CONNECTION_REFUSED¶The class of a remote failure.
CONNECTION_TIMEOUT¶The class of a remote failure.
READ_TIMEOUT¶The class of a remote failure.
SERVER_ERROR¶The class of a remote failure.
AUTHENTICATION¶The class of a remote failure.
NOT_FOUND¶The class of a remote failure.
ALREADY_EXISTS¶The class of a remote failure.
RATE_LIMITED¶The class of a remote failure.
MALFORMED_RESPONSE¶The class of a remote failure.
CLIENT_ERROR¶The class of a remote failure.
VERIFICATION_MISSING¶The class of a remote failure.
VERIFICATION_SUPERSET¶The class of a remote failure.
BRANCH_MOVED¶The class of a remote failure.
TLS¶The class of a remote failure.
SESSION_CLOSED¶The class of a remote failure.
TRANSPORT_ERROR¶The class of a remote failure.