mappersession
Session management tools in python for the libmapper signal mapping framework
Installation
Simply run pip install mappersession in your python environment of choice.
Usage
Usage from the command-line
usage:
mappersession --load PATH [PATH ...] [--interactive] [--wait] [--persist] [--clear]
mappersession --unload PATH [PATH ...]
mappersession --save PATH [--description DESCRIPTION]
mappersession --print_session_tags
options:
-h, --help Show the help message and exit
--load PATH [PATH ...] Mapping session JSON file(s) to load
--unload PATH [PATH ...] Mapper session JSON file(s) to unload
--save PATH Save mapping session as JSON file
--interactive Create libmapper signals for managing file
loading and unloading.
--wait Set if session should wait for missing
devices and signals and connected them as
they appear during session load
--wait_seconds Similar to `--wait` option but only waits
for N seconds
--persist Remain active during session load and
(re)create maps as they appear.
--clear Set if maps should be cleared after saving
and/or before load. Warning – this will
clear all maps regardless of session tag!
--print_session_tags Print a list of active session tags
--description DESCRIPTION Description of session, used when saving
Examples:
Load a session file and wait indefinitely for needed signals to appear:
python -m mappersession --load mysession.json --wait
Load a session file and wait 10 seconds for needed signals to appear:
python -m mappersession --load mysession.json --wait_seconds 10
Unload a session file:
python -m mappersession --unload mysession.json
Replace a running session with another
python -m mappersession --unload sesh1.json --load sesh2.json
Start an interactive session with libmapper control signals for loading/unloading each file:
python -m mappersession --load session1.json session2.json --interactive
Save the current session and provide a description:
python -m mappersession --save mysession.json --description "This session does something cool"
Usage as a Python module
Importing the module
import mappersession as session
Saving a mapping session file
session.save(filename="", description="", values=[],
view_name="", views=[], graph=None)
- param
filename: The name of the file to save - optional param
description: A short description of the current session - optional param
values: Array of {name, value} pairs for signals to set on session load - optional param
view_name: Name of the GUI that's adding metadata - optional param
views: GUI related object for recreating the session - optional param
graph: A previously-allocated libmapper Graph object to use. If not provided one will be allocated internally. - return: The session JSON object
Loading a mapping session file
session.load(filename, interactive=False, wait=False, persist=False, background=False, device_map=None, graph=None)
Loads session files and optionally waits for signals. If the optional argument device_map is provided, mappersession will attempt to match the exact device and signal name, otherwise it will substitute a wildcard for the device name and map to all matching signals. In either case signals belonging to devices that have the property hidden=True will not be matched.
The filename will be included in the session property for loaded maps.
- param
filename(String or List): The session file(s) to load - optional param
interactive(Boolean): Starts an interactive session for managing multiple session files. A libmapper control signal is created for corresponding to each file; setting the control signal value to a non-zero value loads the file, and setting it to zero unloads the file. - optional param
wait(Boolean): Wait for missing signals during session load and create maps once they appear, defaultFalse - optional param
persist(Boolean): Continue running after creating maps in session, and recreate them as matching signals (re)appear, default False - optional param
background(Boolean): True if waiting for signals should happen in a background thread, default False - optional param
device_map(Dict): A dictionary specifying correspondences between device names stored in a session file and names of devices active on the network. - optional param
graph: A previously-allocated libmapper Graph object to use. If not provided one will be allocated internally. - return (Dict): visual session information relevant to GUIs
Unloading a mapping session file
session.unload(filename, graph=None)
Unloads session files by removing maps tagged with the filename using a property named session.
- param
filename(String or List): The session file(s) to unload - optional param
graph: A previously-allocated libmapper Graph object to use. If not provided one will be allocated internally. - return (None)
Loading JSON-formatted session data
session.load_json(session_json, name=None, wait=False, persist=False, background=False, device_map=None, graph=None)
Loads a session JSON Dict with options for staging and clearing. If the optional argument device_map is provided, mappersession will attempt to match the exact device and signal name, otherwise it will substitute a wildcard for the device name and map to all matching signals. In either case signals belonging to devices that have the property hidden=True will not be matched.
If the optional name argument is provided it will be included in the session property for loaded maps.
- param session_json (Dict): A session JSON Dict to load
- optional param
name(String): A name for the session; any maps created by this session will be tagged with the name. - optional param
wait(Boolean or Float): Wait for missing signals during session load and create maps once they appear, defaultFalse. Can be set to wait indefinitly (True) or for N seconds. - optional param
persist(Boolean): Continue running after creating maps in session, and recreate them as matching signals (re)appear, default False - optional param
background(Boolean): True if waiting for signals should happen in a background thread, default False - optional param
device_map(Dict): A dictionary specifying correspondences between device names stored in a session file and names of devices active on the network. - optional param
graph: A previously-allocated libmapper graph object to use. If not provided one will be allocated internally. - return (Dict): visual session information relevant to GUIs
Get a list of active session tags
session.tags(graph=None)
- optional param
graph: A previously-allocated libmapper graph object to use. If not provided one will be allocated internally. - return (List): a list of active session tags
Metadata
Release files for mappersession 0.0.18
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mappersession-0.0.18-py3-none-any.whl | Python 3 | none | any | Details for mappersession-0.0.18-py3-none-any.whl |
Release files / mappersession-0.0.18-py3-none-any.whl
| Download URL | mappersession-0.0.18-py3-none-any.whl |
|---|---|
| Size | 21.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e7ff27e6c27269d445d6de8800c4835ad97883dc4dd97dcb106e30ba7aee6f64
|
|
BLAKE2b-256 checksum How to use checksums |
9a9c7c8d50ca55c5a046576f5d0446245fbc0f9cc7d048ff7d1613b4e27bd1f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
Security for mappersession 0.0.18
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.