Metadata-Version: 2.1
Name: steam_sdk
Version: 2026.10.4
Summary: Source code for APIs for STEAM tools.
Home-page: https://gitlab.cern.ch/steam/steam_sdk
Author: STEAM Team
Author-email: steam-team@cern.ch
Keywords: SDK,API,STEAM,CERN
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: all
Provides-Extra: docs
Provides-Extra: test
Provides-Extra: build

# STEAM_SDK

Source code for STEAM SDK and various APIs.
(Copyright © 2022, CERN, Switzerland. All rights reserved.)

# Folders Structure
![Alt text](documents/STEAM_SDK_folder_structure.svg)

# User settings
Important: Before running the tests, make sure to set up your user settings.

* The settings file must be located in the subfolder steam_sdk\tests
* The file must be called settings.username.yaml, where username is your user name in the machine on which you are running the analysis.
It is recommended to start by making a copy of the example settings.SYSTEM.yaml file.
* Note: It is not recommended to change other settings files within this project (some files are generated by the software).

# Documentation
https://steam-sdk.docs.cern.ch/

# Installation

pip install steam-sdk

# Test model library (`steam_models` submodule)

The magnet input models used by the tests live in the shared
[`steam_models`](https://gitlab.cern.ch/steam/steam_models) repository, included here as a
**git submodule** at `tests/_inputs_steam_models/` (magnets under `tests/_inputs_steam_models/magnets/<MAGNET>/input/`). It is
pinned to a specific `steam_models` commit and configured as a *shallow* submodule (only the pinned
revision is fetched, not the full history — `steam_models` is several GB).

## First checkout — get the submodule

Clone with the submodule in one step:

```bash
git clone --recurse-submodules ssh://git@gitlab.cern.ch:7999/steam/steam_sdk.git
```

Already cloned without it? Initialise it (shallow):

```bash
git submodule update --init --recommend-shallow tests/_inputs_steam_models
```

**PyCharm:** on first opening a project with a submodule, PyCharm asks *“Would you like to check out
the submodules?”* — click **Yes**. If dismissed, run **Git ▸ Update Project…** (Ctrl+T / ⌘T) and
PyCharm checks the submodule out to the pinned commit.

## Sync the submodule to the pinned commit

After pulling changes where someone moved the submodule pointer:

```bash
git submodule update --init --recommend-shallow tests/_inputs_steam_models
```

**PyCharm:** **Git ▸ Update Project…** (Ctrl+T / ⌘T) updates submodules to the pinned commit as part
of the project update.

## Update the submodule to the latest `steam_models`

To pull the newest magnet models (move the pin to the current `steam_models` `master`):

```bash
git submodule update --remote tests/_inputs_steam_models   # fetch steam_models master and check it out
git add steam_models                          # record the new pin in this repo
git commit -m "Bump steam_models submodule"
```

**PyCharm:** there is no one-click “advance submodule to latest” button — use the built-in **Terminal**
(Alt+F12) for the commands above, or open `steam_models/` as its own project, `git pull` there, then
commit the moved pointer in this repo (**Git ▸ Commit**, then **Git ▸ Push**).

> The submodule uses a **relative URL** (`../steam_models.git`), so it resolves over whatever transport
> you cloned this repo with (SSH for developers, HTTPS for CI) — no per-user URL tweaking.

# Links
STEAM website: https://cern.ch/steam
SDK section: https://steam.docs.cern.ch/tools/sdk/

# Contact
steam-team@cern.ch

# STEAM User Agreement
By using any software of the STEAM framework, users agree with this document:
https://edms.cern.ch/document/2024516
