seamm_manager package

Submodules

seamm_manager.apps module

Handle the apps for SEAMM.

seamm_manager.apps.create()

Create the requested apps.

seamm_manager.apps.delete()

seamm_manager.apps.refresh_apps()

Bring the installed apps up to date after an update.

Sets each app’s version to its package’s and, on macOS, replaces the shell script launcher of bundles made by older versions with the compiled one (a script makes Apple Silicon Macs without Rosetta ask to install it). Apps that are not installed are left alone. Returns the names refreshed.

seamm_manager.apps.setup(parser)

Define the command-line interface for handling the apps.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.apps.show()

seamm_manager.apps.update()

seamm_manager.cache module

Handle the cache for SEAMM components.

seamm_manager.cache.refresh()

seamm_manager.cache.setup(parser)

Define the command-line interface for installing SEAMM components.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.cli module

Define the command-line interface for the SEAMM installer.

seamm_manager.cli.setup(parser)

Setup the command-line interface for the SEAMM manager.

Parameters:

• parser (argparse.ArgumentParser) – The main parser for the application.

• logger (logging.Logger) – The logger for output.

• environment (str) – The Conda environment name

seamm_manager.conda module

class seamm_manager.conda.Conda(logger=<Logger seamm_manager.conda (WARNING)>)

Bases: object

Class for handling conda

activate(environment)

Activate the requested environment.

property active_environment

The currently active Conda environment.

create_environment(environment_file, name=None, force=False)

Create a Conda environment.

Parameters:

• environment_file (str or pathlib.Path) – The name or path to the environment file.

• name (str = None) – The name of the environment. Defaults to that given in the environment file.

• force (bool = False) – Whether to overwrite an existing environment.

delete_environment(name)

Delete a Conda environment.

Parameters:

name (str) – The name of the environment.

property environments

The available conda environments.

exists(environment)

Whether an environment exists.

Parameters:

environment (str) – The name of the environment.

Returns:

True if the environment exists, False otherwise.

Return type:

bool

export_environment(environment, path=None)

Export the definition of an environment.

Parameters:

• environment (str) – The name of the environment to export

• path (str or pathlib.Path = None) – An optional filename to export to

install(package, environment=None, channels=None, override_channels=True, progress=True, newline=True, update=None)

Install a package in an environment..

Parameters:

• package (strip) – The package to install.

• environment (str) – The name of the environment to list, defaults to the current.

• channels ([str] = None) – A list of channels to search. defaults to the list in self.channels.

• override_channels (bool = True) – Ignore channels configured in .condarc and the default channel.

• progress (bool = True) – Whether to show progress dots.

• newline (bool = True) – Whether to print a newline at the end if showing progress

• update (None or method) – Method to call to e.g. update a progress bar

property is_installed

Whether we have access to conda.

list(environment=None, query=None, fullname=False, update=None, explicit=False)

The contents of an environment.

Parameters:

• environment (str) – The name of the environment to list, defaults to the current.

• query (str) – Regexp for package names, default to all packages

• fullname (bool = False) – For a query, match only the full name

• update (None or method) – Method to call to e.g. update a progress bar

• explicit (bool = False) – If true, get an explicit list, suitable for “conda create –file”

Returns:

A dictionary keyed by the package names.

Return type:

dict

path(environment)

The path for an environment.

Parameters:

environment (str) – The name of the environment to remove.

Returns:

The path to the environment.

Return type:

pathlib.Path

property prefix

The path for the conda root.

remove_environment(environment)

Remove an existing environment.

Parameters:

environment (str) – The name of the environment to remove.

property root_prefix

The root prefix of the conda installation.

search(query=None, channels=None, override_channels=True, progress=True, newline=True, update=None)

Run conda search, returning a dictionary of packages.

Parameters:

• query (str = None) – The pattern to search, Defaults to None, meaning all packages.

• channels ([str] = None) – A list of channels to search. defaults to the list in self.channels.

• override_channels (bool = True) – Ignore channels configured in .condarc and the default channel.

• progress (bool = True) – Whether to show progress dots.

• newline (bool = True) – Whether to print a newline at the end if showing progress

• update (None or method) – Method to call to e.g. update a progress bar

Returns:

A dictionary of packages, with versions for each.

Return type:

dict

show(package)

Show the information for a single package.

Parameters:

package (str) – The name of the package.

uninstall(package, environment=None, channels=None, override_channels=True, progress=True, newline=True, update=None)

Uninstall a package from an environment..

Parameters:

• package (str or [str]) – The package to uninstall install.

• environment (str) – The name of the environment to list, defaults to the current.

• channels ([str] = None) – A list of channels to search. defaults to the list in self.channels.

• override_channels (bool = True) – Ignore channels configured in .condarc and the default channel.

• progress (bool = True) – Whether to show progress dots.

• newline (bool = True) – Whether to print a newline at the end if showing progress

• update (None or method) – Method to call to e.g. update a progress bar

update(package=None, environment=None, channels=None, override_channels=True, progress=True, newline=True, all=False, update=None)

Update a package in an environment..

Parameters:

• package (strip) – The package to update.

• environment (str) – The name of the environment to list, defaults to the current.

• channels ([str] = None) – A list of channels to search. defaults to the list in self.channels.

• override_channels (bool = True) – Ignore channels configured in .condarc and the default channel.

• progress (bool = True) – Whether to show progress dots.

• newline (bool = True) – Whether to print a newline at the end if showing progress

• all (bool = False) – Fully update the environment.

• update (None or method) – Method to call to e.g. update a progress bar

update_environment(environment_file, name=None, update=None, pip_policy='conservative')

Update a Conda environment from an environment file.

Parameters:

• environment_file (str or pathlib.Path) – The name or path to the environment file.

• name (str = None) – The name of the environment. Defaults to the current environment.

• pip_policy (str = "conservative") – How the file’s pip: section is applied. "conda" lets conda do it, which runs pip install -U and so upgrades every pip package, including a bare torch that a machine may hold at a driver-matched build. "conservative" (the default) applies the conda part with conda, then bare pip names without upgrading (they must merely be present) and requirements with a version specifier with -U (kept current within their spec).

seamm_manager.conda.find_conda()

The path to the conda executable, or None.

Tries, in order: $CONDA_EXE (set by an activated conda shell), the PATH, then the usual installation directories. When found somewhere other than the PATH, its directory is added to the PATH so that sub-processes (conda run, the plug-in installers) find it too.

seamm_manager.conda.split_environment_file(environment_file)

Split a conda environment file into its conda part and its pip part.

Returns:

The YAML text of the file without its pip: entry; the pip requirements that are bare names (torch); and those carrying a version specifier or other qualification (xnns>=0.3.0, e3nn==0.4.4, a URL, pkg[extra]).

Return type:

(str, [str], [str])

seamm_manager.configuration module

A class for reading, updating and writing the configuration file.

This class handles the configuration (.ini) file as text, so that comments in the file are preserved.

class seamm_manager.configuration.Configuration(path=None)

Bases: object

add_prolog(text='', force=False)

Add the prolog to the configuration.

Parameters:

• text (str = '') – The body of the prolog, which should be just comments.

• force (bool = True) – Whether to overwrite an existing prolog.

add_section(name, text='', force=False)

Add a new section to the configuration.

Parameters:

• name (str) – The name of the section.

• text (str = '') – The body of the section, which must be properly formatted.

• force (bool = True) – Whether to overwrite an existing section of the same name.

file_exists()

Whether the configuration file exists.

from_string(text)

Replace the contents of the configuration with those from text.

Parameters:

text (str) – The configuration data as text.

get_prolog()

Return the prolog of the file, if any.

Returns:

The prolog of the configuration.

Return type:

str

get_values(section)

Return the values in a section as a dictionary.

Returns an empty dictionary if the section does not exist, or if it does not contain any keyword definitions. Use section_exists to differentiate.

Parameters:

section (str) – The name of the section to retrieve.

Returns:

A dictionary of keyword-value pairs, as strings.

Return type:

dict

property path

The path to the configuration file.

save()

Save the current configuration to disk.

section_exists(section)

Return whether a section exits in the configuration.

Parameters:

section (str) – The name of the section.

Returns:

True if the section exists; False otherwise.

Return type:

bool

sections()

Return a list of sections in the configuration.

Returns:

The list of sections.

Return type:

[str]

set_value(section, key, value, strict=False)

Set the key in a section.

Parameters:

• section (str) – The section to work with.

• key (str) – The key to set in the section.

• value (str) – The value to set the key to.

• strict (bool = False) – Raise an error is the key does not already exist.

to_string(section=None)

Create the text of a section.

Parameters:

section (str) – The name of the section. Defaults to the entire file.

seamm_manager.datastore module

Handle the datastore for SEAMM.

seamm_manager.datastore.db_version()

Return the version of the database.

seamm_manager.datastore.ensure(default_project='default')

Create the datastore if it does not exist, using the environment’s own seamm_datastore, so that the JobServer and the web interface can start in any order. Returns True if it was created.

The first version of the manager left this to the web interface’s first start; a JobServer created before it crash-looped on the missing database.

seamm_manager.datastore.latest_version()

Show information about the datastore.

seamm_manager.datastore.setup(parser)

Define the command-line interface for handling services.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.datastore.show()

Show information about the datastore.

seamm_manager.datastore.update()

Update the database to the latest version.

seamm_manager.datastore.update_db()

Update the database to the latest version.

seamm_manager.environment module

The ‘environment’ command: create, show, recreate or remove the uv-managed Python environment that holds SEAMM.

seamm_manager.environment.create(python_version=None)

seamm_manager.environment.ensure(python_version=None)

Create the environment if it does not exist. Returns True if created.

seamm_manager.environment.recreate()

seamm_manager.environment.remove()

seamm_manager.environment.setup(parser)

Define the command-line interface for the environment.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.environment.show()

seamm_manager.gui module

class seamm_manager.gui.GUI(logger=<Logger seamm_manager.gui (WARNING)>)

Bases: MutableMapping

about()

cancel()

event_loop()

property gui_only

Whether to install only the GUI.

handle_dbg_level(level)

layout_apps()

Redraw the apps table in the GUI.

layout_services()

Redraw the services table in the GUI.

preferences()

refresh()

Update the table of packages.

refresh_apps()

refresh_services()

reset_table()

Redraw the table in the GUI.

setup()

seamm_manager.install module

Install requested components of SEAMM.

seamm_manager.install.install()

Install the requested SEAMM components and plug-ins.

Parameters:

options (argparse.Namespace) – The options from the command-line parser.

seamm_manager.install.install_development_environment()

Install packages needed for development, from the package list’s ‘development packages’ (falling back to a built-in list).

seamm_manager.install.install_packages(to_install, update=False, third_party=False, gui_only=False, progress=None, update_text=None)

Install SEAMM components and plug-ins.

seamm_manager.install.install_seamm_webui(update=False)

Create/update the dedicated venv-webui environment under the root and install (or upgrade) seamm_webui into it from PyPI.

seamm_webui is not in the package list and, being a daemon rather than a plug-in, lives in its own environment rather than the main one. Its own runtime dependencies (fastapi, uvicorn, …) are declared in its PyPI package and resolved by uv here, not duplicated.

seamm_manager.install.setup(parser)

Define the command-line interface for installing SEAMM components.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.installer_base module

class seamm_manager.installer_base.InstallerBase(ini_file='~/.seamm.d/seamm.ini', logger=<Logger seamm_manager.installer_base (WARNING)>)

Bases: object

A base class for plug-in installers.

This base class provides much of the functionality needed by installers for plug-ins, but not the functionality specific to a given plug-in.

section

The section of the configuration file to use. Defaults to None.

Type:

str

ask_yes_no(text, default=None)

Ask a simple yes/no question, returning True/False.

Parameters:

text (str) – The text of the question.

Returns:

True for yes; False, no

Return type:

bool

check()

Check the installation and fix errors if requested.

If the option yes is present and True, this method will attempt to correct any errors in the configuration file. Use –yes on the command line to enable this.

The information in the configuration file is:

installation

How the executables are installed. One of user, modules or conda

conda-environment

The Conda environment if and only if installation = conda

modules

The environment modules if installation = modules

{self.path_name}

The path where the executables are. Automatically defined if installation is conda or modules, but given by the user is it is user.

Returns:

True if everything is OK, False otherwise. If yes is given as an option, the return value is after fixing the configuration.

Return type:

bool

check_configuration_file()

Checks that the necessary section for the plug-in is in the configuration file.

check_exe_configuration_file()

Checks that the init file for the executable for the plug-in exists.

property code_environments

own, shared or prefixed.

See seamm_manager.policy. In a shared installation the plug-ins never create, update or remove a conda environment.

Type:

This installation’s code-environment policy

property conda

The Conda object to use for accessing Conda.

property configuration

The Configuration object for working with the ini file.

property exe_config

executables_in_path()

Check whether the executables are found in the PATH.

Returns:

The path where the executables are, or None.

Return type:

pathlib.Path

have_executables(path)

Check whether the executables are found at the given path.

Parameters:

path (pathlib.Path) – The directory to check.

Returns:

True if all of the executables are found.

Return type:

bool

property init_file_name

The initialization file for the executable.

install()

Install using a Conda environment.

A plug-in whose code cannot be installed this way (ORCA, Gaussian, VASP, … are licensed manual installations) has no environment_file; say so instead of failing.

property pip

The Pip object used for working with pip.

property root

The root of the SEAMM installation being worked on.

In order: SEAMM_ROOT, which seamm-manager sets for the installation it is working on; root in the [SEAMM] section of the per-user seamm.ini (deprecated, since every installation shares that file); the installation this Python belongs to (<root>/venv); ~/SEAMM. The codes’ .ini files are written here.

run()

Do what the user asks via the commandline.

setup_parser()

Parse the command line into the options.

property shared_codes

Whether this installation uses the default installation’s codes.

show()

Show the current installation status.

uninstall()

Uninstall the Conda environment.

update()

Update the installation, if possible.

In a shared installation this only reports: the default installation keeps the codes up to date.

seamm_manager.linux module

Linux OS specific routines handling unique operations.

• Installing daemons to handle the Dashboard and JobServer

class seamm_manager.linux.ServiceManager(prefix='')

Bases: object

create(name, exe_path, *args, user_agent=True, user_only=True, stderr_path=None, stdout_path=None, exist_ok=False)

Create a service on Linux.

Linux supports three types of services. This function uses user_agent and user_only to control which is selected.

1. A user service for a single user, which runs while that user is logged in. (True, True)

2. A service installed by the admin that is available for all users, and runs when any user is logged in. (True, False)

3. A system-wide service that runs when the machine is booted. (False, not used)

Parameters:

• name (str) – The name of the agent

• exe_path (pathlib.Path or str) – The path to the executable (required). Either a path-like object or string

• args ([]) – List of arguments for the program.

• user_agent (bool = True) – Whether to create a per-user agent (True) or system-wide daemon (False)

• user_only (bool = True) – Whether to install for just the current user (True) or all users (False). Only affects user agents, not daemons which are always system-wide.

• stderr_path (pathlib.Path or str = None) – The file to direct stderr. Defaults to “~/SEAMM/logs/<name>.out”

• stdout_path (pathlib.Path or str = None) – The file to direct stdout. Defaults to “~/SEAMM/logs/<name>.out”

• exist_ok (bool = False) – If True overwrite an existing file.

property data

delete(service, ignore_errors=False)

file_path(service)

Return the path to the unit file for the service.

is_installed(service)

is_running(service)

list()

property paths

restart(service, ignore_errors=False)

start(service, ignore_errors=False)

status(service)

stop(service, ignore_errors=False)

property uid

seamm_manager.linux.create_app(exe_path, *args, name='SEAMM', comment='the Simulation Environment for Atomistic and Molecular Modeling', user_only=False, icons=None, **kwargs)

Create an application bundle for a Linux app.

Parameters:

• exe_path (pathlib.Path or str) – The path to the executable (required). Either a path-like object or string

• name (str) – The name of the app

• comment (str = "the Simulation Environment for Atomistic and Molecular Modeling") – A comment for use in tooltips, etc.

• user_only (bool = False) – Whether to install for just the current user or all users (default).

• icons (pathlib.Path or str) – Optional path to the icns files to use.

• kwargs – Other keywords arguments for compatibility with other OS’s. Ignored

seamm_manager.linux.delete_app(name, missing_ok=False)

Delete the app given.

Parameters:

• name (str) – The name of the app.

• missing_ok (bool = False) – Don’t throw an error if the app does not exist.

seamm_manager.linux.get_apps()

Return a list of all user applications.

Returns:

{str – Dictionary of app names and paths to the desktop file.

Return type:

str}

seamm_manager.linux.list_to_dict(lst)

seamm_manager.linux.update_app(name, version, missing_ok=False)

Update the version for a Linux app.

Since the desktop file does not have the version, nothing to do.

Parameters:

• name (str) – The name of the app

• version (str) – The version of the app.

• missing_ok (bool = False) – Don’t throw an error if the app does not exist.

seamm_manager.mac module

Mac OS specific routines handling unique operations.

• Creating the ‘app’

• Installing Launch Agents to handle the Dashboard and JobServer

class seamm_manager.mac.ServiceManager(prefix='')

Bases: object

create(name, exe_path, *args, user_agent=True, user_only=True, stderr_path=None, stdout_path=None, exist_ok=False, environment=None)

Create a service on MacOS.

The Mac supports three types of services. This function uses user_agent and user_only to control which is selected.

1. A user Launch Agent for a single user, which runs while that user is logged in. (True, True)

2. A Launch Agent installed by the admin that is available for all users, and runs when any user is logged in. (True, False)

3. A system-wide service that runs when the machine is booted. (False, not used)

Parameters:

• name (str) – The name of the agent

• exe_path (pathlib.Path or str) – The path to the executable (required). Either a path-like object or string

• args ([]) – List of arguments for the program.

• user_agent (bool = True) – Whether to create a per-user agent (True) or system-wide daemon (False)

• user_only (bool = True) – Whether to install for just the current user (True) or all users (False). Only affects user agents, not daemons which are always system-wide.

• stderr_path (pathlib.Path or str = None) – The file to direct stderr. Defaults to “~/SEAMM/logs/<name>.out”

• stdout_path (pathlib.Path or str = None) – The file to direct stdout. Defaults to “~/SEAMM/logs/<name>.out”

• exist_ok (bool = False) – If True overwrite an existing file.

• environment (dict(str, str) = None) – Environment variables to set for the service.

property data

delete(service, ignore_errors=False)

file_path(service)

Return the path to the plist file for the service.

is_installed(service)

is_running(service)

list()

property paths

restart(service, ignore_errors=False)

start(service, ignore_errors=False)

status(service)

stop(service, ignore_errors=False)

property uid

seamm_manager.mac.create_app(exe_path, *args, identifier=None, name='SEAMM', version='0.1.0', user_only=False, icons=None, copyright=None)

Create an application bundle for a Mac app.

Parameters:

• exe_path (pathlib.Path or str) – The path to the executable (required). Either a path-like object or string

• identifier (str) – The bundle identifier. If None, is set to ‘org.molssi.seamm.<name>’.

• name (str) – The name of the app

• version (str = "0.1.0") – The version of the app.

• user_only (bool = False) – Whether to install for just the current user. Defaults to all users.

• icons (pathlib.Path or string) – Optional path to the icns file to use.

• copyright (str) – The human-readable copyright. Defaults to “Copyright 2017-xxxx MolSSI”

seamm_manager.mac.create_service_bundle(directory, name, python, icons)

Make an app bundle whose executable is the Python interpreter itself.

A service run as <venv>/bin/seamm-jobserver shows up everywhere on macOS as python3.12, because the process is named after the program file that runs, the interpreter. With the interpreter inside <name>.app the process is called <name> and Activity Monitor shows the bundle’s icon. uv’s Python is a single statically linked file, so a hard link is enough.

The service must set __PYVENV_LAUNCHER__ to the venv’s bin/python so that the interpreter uses the venv (CPython reads it at startup on macOS, as the python.org launcher does, and removes it from the environment).

Parameters:

• directory (pathlib.Path) – Where to put the bundle, e.g. <root>/services.

• name (str) – The bundle’s name, which is also the process name, e.g. SEAMM-JobServer.

• python (pathlib.Path or str) – The venv’s bin/python; the interpreter it resolves to is linked.

• icons (pathlib.Path or str) – The icns file for the bundle.

Returns:

The bundle’s executable, to run in place of python.

Return type:

pathlib.Path

seamm_manager.mac.delete_app(name, missing_ok=False)

Delete the app given.

Parameters:

• name (str) – The name of the app.

• missing_ok (bool = False) – Don’t throw an error if the app does not exist.

seamm_manager.mac.get_apps()

seamm_manager.mac.install_launcher(contents_path, name, script)

Put the compiled launcher and the script it runs into an app bundle.

macOS needs a bundle’s executable to be a compiled program. A shell script carries no architecture, so on Apple Silicon without Rosetta the system asks the user to install Rosetta before launching it. The universal launcher shipped in data/macos_launcher (source beside it) runs Contents/Resources/<name>.sh with bash instead.

Parameters:

• contents_path (pathlib.Path) – The bundle’s Contents directory.

• name (str) – The app’s name, which is also the executable’s (CFBundleExecutable).

• script (str) – The text of the shell script to run.

seamm_manager.mac.is_macho(path)

Whether the file is a compiled Mach-O program (not a script).

seamm_manager.mac.refresh_service_bundle(bundle_path)

Re-link a service bundle’s interpreter if its environment’s has changed.

Returns True if the link was remade (the service picks it up when it next restarts), False if it was current or the bundle is not a service bundle.

seamm_manager.mac.update_app(name, version, missing_ok=False)

Update the version for a Mac app.

Parameters:

• name (str) – The name of the app

• version (str) – The version of the app.

• missing_ok (bool = False) – Don’t throw an error if the app does not exist.

seamm_manager.metadata module

Metadata about packages, etc.

seamm_manager.my module

Global module for passing around objects and constants.

seamm_manager.naming module

Names of an installation’s services, apps and service bundles.

Several SEAMM installations can live on one machine (~/SEAMM, ~/SEAMM_DEV, ~/SEAMM_NEW, …). Each is identified by a tag: empty for the default installation ~/SEAMM, otherwise the root’s directory name with its case kept (or the --name given to the manager). The default installation keeps the plain names (jobserver, SEAMM); any other gets the tag in its names (jobserver-SEAMM_DEV, SEAMM (SEAMM_DEV)), so installations never collide.

seamm_manager.naming.app_name(app)

The desktop app’s name for this installation, e.g. SEAMM (SEAMM_DEV).

seamm_manager.naming.bundle_name(base)

A service bundle’s name for this installation, e.g. SEAMM-JobServer-SEAMM_DEV.

seamm_manager.naming.compute_tag(root, name=None)

The tag for the installation at root.

Parameters:

• root (str or pathlib.Path) – The installation’s root.

• name (str = None) – An explicit name for the installation, which wins.

Returns:

“” for the default installation ~/SEAMM.

Return type:

str

seamm_manager.naming.same_root(a, b)

Whether two root paths name the same directory.

seamm_manager.naming.service_kind(name)

The kind of a SEAMM service from its name: jobserver, webui or dashboard.

Handles the current names (jobserver, jobserver-SEAMM_NEW) and the older development names (dev_jobserver).

seamm_manager.naming.service_name(service)

The service’s name for this installation, e.g. jobserver-SEAMM_DEV.

seamm_manager.naming.tag()

The current installation’s tag.

seamm_manager.pip module

class seamm_manager.pip.Pip

Bases: object

Class for handling pip

install(package)

Install the requested package.

Parameters:

package (str) – The package of interest.

list(outdated=False, uptodate=False)

List the installed packages.

Parameters:

• outdated (bool) – If true, list only the outdated packages. Cannot be used with uptodate.

• uptodate (bool) – If true, list only the up-to-date packages. Cannot be used with outdated.

search(query=None, framework=None, exact=False, progress=False, newline=True, update=None)

Search PyPi for packages.

Parameters:

• query (str) – The text of the query, if any.

• framework (str) – The framework classifier, if any.

• exact (bool = False) – Whether to only return the exact match, defaults to False.

• progress (bool = False) – Whether to show progress dots.

• newline (bool = True) – Whether to print a newline at the end if showing progress

• update (None or method) – Method to call to e.g. update a progress bar

Returns:

A list of packages matching the query.

Return type:

[str]

show(package)

Return the information for an installed package.

Parameters:

package (str) – The package of interest.

uninstall(package)

Remove the requested packages.

Parameters:

package (str or [str]) – The package of interest.

update(package)

Update the requested package.

Parameters:

package (str) – The package of interest.

seamm_manager.policy module

How an installation gets the external codes’ conda environments.

Every installation on a machine would otherwise share the codes’ conda environments by name (seamm-lammps, seamm-mopac, …), so installing or updating plug-ins in a trial installation could change production’s codes. Each installation therefore has a code-environment policy, kept in <root>/installation.ini:

own

The plug-ins create and update the codes’ environments, as always. The default, and the only choice, for the default installation ~/SEAMM.

shared

The plug-ins never create, update or remove a conda environment. Installing a plug-in copies the default installation’s <code>.ini into this root, so the code runs from the same environment, and reports a code the default installation does not have; updating only reports. The default for any other root.

prefixed

The installation has its own copies, named seamm-<tag>-<code> (e.g. seamm-SEAMM_NEW-lammps), for testing new versions of the codes themselves.

(The file is not <root>/seamm.ini: seamm_util still moves an old ~/SEAMM/seamm.ini into ~/.seamm.d.)

seamm_manager.policy.code_environment_policy(root)

The installation’s code-environment policy: own, shared or prefixed.

seamm_manager.policy.is_default_root(root)

Whether root is the default installation, ~/SEAMM.

seamm_manager.policy.prefixed_environment(name, tag)

The installation’s own copy of a code environment: seamm-<tag>-<code>.

seamm_manager.policy.set_code_environment_policy(root, policy)

Record the installation’s code-environment policy.

seamm_manager.services module

Handle the services (daemons) for SEAMM.

seamm_manager.services.create()

seamm_manager.services.create_service(service, force=False, port=None, dashboard_name=None, webui_host='0.0.0.0')

Create and start one of this installation’s services.

Parameters:

• service (str) – “jobserver”, “webui” or “dashboard”.

• force (bool = False) – Recreate the service if it exists.

• port (int = None) – The web interface’s or dashboard’s port. Default: the service’s current port, else that of a same-root service it replaces, else the first free port from 55055.

• dashboard_name (str = None) – The dashboard’s name. Default: the host name, plus the installation’s tag.

• webui_host (str = "0.0.0.0") – The address the web interface listens on.

Returns:

Whether the service was created.

Return type:

bool

seamm_manager.services.delete()

seamm_manager.services.free_port(exclude=(), start=55055)

The first port from start that no other SEAMM service uses and is free.

seamm_manager.services.refresh_service_bundles()

Keep the macOS service bundles in step with their environments.

Re-links a bundle’s interpreter when its environment’s Python has changed (effective at the service’s next restart), and points out services still run directly as python3.12. Returns the bundles re-linked.

seamm_manager.services.restart()

seamm_manager.services.same_root_services(service)

Other SEAMM services of this kind started with this installation’s root.

Whatever their names – the older dev_jobserver, or one made by hand – two services of one kind on one root would share a datastore, so creating a service replaces them.

seamm_manager.services.setup(parser)

Define the command-line interface for handling services.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.services.show()

seamm_manager.services.start()

seamm_manager.services.status()

seamm_manager.services.stop()

seamm_manager.show module

Show the status of the SEAMM installation.

seamm_manager.show.setup(parser)

Define the command-line interface for installing SEAMM components.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.show.show()

seamm_manager.uninstall module

Uninstall requested components of SEAMM.

seamm_manager.uninstall.setup(parser)

Define the command-line interface for removing SEAMM components.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.uninstall.uninstall()

Uninstall the requested SEAMM components and plug-ins.

With –all the whole environment is removed after the plug-ins’ own uninstallers (for the external codes) have run.

seamm_manager.uninstall.uninstall_packages(to_uninstall, gui_only=False)

Uninstall SEAMM components and plug-ins.

seamm_manager.update module

Update requested components of SEAMM.

seamm_manager.update.setup(parser)

Define the command-line interface for updating SEAMM components.

Parameters:

parser (argparse.ArgumentParser) – The main parser for the application.

seamm_manager.update.update()

Update the requested SEAMM components and plug-ins.

seamm_manager.update.update_development_environment()

Update packages needed for development.

seamm_manager.update.update_packages(to_update, gui_only=False, progress=None, update_text=None, latest=False)

Update SEAMM components and plug-ins.

The version to update to normally comes from the nightly package list, and the install is constrained to the matching lock file. With latest each package’s newest release on PyPI is used when it is newer than the list’s, pinned exactly, and the lock is not applied (it would pin the older version); PyPI being unreachable falls back to the list for that package.

seamm_manager.util module

Utility methods for the SEAMM installer.

class seamm_manager.util.JSONDecoder(**kwargs)

Bases: JSONDecoder

Class for handling the package versions in JSON.

dict_to_object(d)

class seamm_manager.util.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Class for handling the package versions in JSON.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

seamm_manager.util.constraints()

The lock file to pass to uv, or None if the user opted out or it is missing.

seamm_manager.util.find_packages(progress=True, update=None, update_cache=False, cache_valid=1)

Fetch the package list and its lock file from Zenodo.

The package list (SEAMM_packages.json, format 2) gives every package the manager handles with its current version and type. The lock file (seamm.lock.txt) is the universal set of pinned versions that resolved together; it is saved under <root>/environments and passed to uv as constraints so installations are reproducible.

Returns:

name -> {“description”, “type”, “version”}

Return type:

dict(str, dict)

seamm_manager.util.get_metadata()

Get the metadata for this installation.

Returns:

{str – A dictionary of the metadata.

Return type:

any}

seamm_manager.util.initialize()

Set up the conda and pip wrappers. Conda is only needed for the external codes’ own environments, so its absence is not an error here; the plug-in installers report it when they need it.

seamm_manager.util.package_info(package, conda_only=False)

Return info on a package in the SEAMM environment.

Parameters:

package – The name of the package.

Returns:

The installed version and “pypi”, or (None, None) if not installed.

Return type:

(str, str)

seamm_manager.util.pypi_latest(package, timeout=10)

The newest release of package on PyPI, or None if it cannot be found.

Asks PyPI’s simple index (the JSON form of PEP 691) – the index uv installs from – so a release made after the nightly package list is visible at once and is certainly installable. (PyPI’s JSON API was used before, but its CDN served a stale copy to Python’s requests while the simple index already had the release.) Pre-releases and yanked files are ignored. Network problems, an unknown project or an odd response give None: the caller falls back to the package list.

seamm_manager.util.retire_installer(specs, installed)

Remove seamm-installer from the environment before seamm-manager goes in.

Both provide the seamm_installer module (the manager ships it as a compatibility shim for the plug-ins’ installers), so they cannot coexist in one environment. Returns True if it was removed.

seamm_manager.util.run_plugin_installer(package, *args, verbose=True)

Run the plug-in installer with given arguments.

Parameters:

• package – The package name for the plug-in. Usually xxxx-step.

• args – Command-line arguments for the plugin installer.

Returns:

The result structure from subprocess.run, or None if there is no installer.

Return type:

xxxx

seamm_manager.util.set_metadata(metadata)

Set the metadata for this installation.

Parameters:

{str (any}) – A dictionary of the metadata.

seamm_manager.util.sync_manager()

Put the running manager’s own release into the environment.

The package list (and lock) on Zenodo names the manager version current when the nightly job last ran, so for up to a day after a release the environment would get the previous manager – and the plug-ins’ installers run with that copy. If this manager is a clean release newer than what the environment holds, install exactly this version there, outside the lock’s constraints (only this package). Returns the version installed, or None if nothing was done.

seamm_manager.util.write_environment_snapshot(tag)

Record uv pip freeze under <root>/environments as the audit trail.

seamm_manager.uv module

The uv-managed Python environment that holds SEAMM.

Uv wraps the uv executable for one virtual environment, by default <root>/venv. Every SEAMM package and every Python dependency is installed into it from PyPI with uv pip install; the interpreter itself comes from uv python install. Nothing here touches conda: the external codes’ own environments are handled by the plug-in installers.

class seamm_manager.uv.Uv(root, name='venv', python_version='3.12')

Bases: object

A uv-managed virtual environment.

Parameters:

• root (pathlib.Path or str) – The SEAMM root; the environment lives in <root>/venv.

• name (str = "venv") – The environment directory name under the root.

• python_version (str = "3.12") – The interpreter version to install when creating the environment.

bin(name)

The path an executable name would have in this environment.

property bin_path

create(python_version=None, seed=True)

Create the environment, installing the interpreter if needed.

seed adds pip to the environment, which some tools (and the docs builds) expect to find as python -m pip.

property exists

freeze()

The pip freeze text for the environment (the audit trail).

install(packages, constraints=None, upgrade=False, refresh=True)

Install packages into the environment.

Parameters:

• packages (str or [str]) – Requirement specifiers, e.g. "seamm" or "seamm==2026.9.25".

• constraints (pathlib.Path or str = None) – A constraints file (the published lock) passed with -c.

• upgrade (bool = False) – Upgrade the named packages to the newest allowed versions.

• refresh (bool = True) – Ignore uv’s cached view of the index, so a release published minutes ago is seen. Without it uv can reuse stale index metadata and report nothing to do.

list()

The installed packages: {normalized name: {"version": str}}.

property path

The environment directory.

property python

The environment’s interpreter.

python_version_installed()

The ‘X.Y.Z’ version of the environment’s interpreter, or None.

remove()

Delete the environment directory.

run(*args, check=True, capture=True)

Run uv <args> and return the CompletedProcess.

Raises UvError with uv’s output if the command fails and check.

tool_upgrade(tool='seamm-manager')

Upgrade a uv tool (the manager’s own installation) to the newest release. Returns True if it succeeded.

Not uv tool upgrade: that reuses uv’s cached view of the index and can report “Nothing to upgrade” minutes after a release. A forced reinstall with --refresh always consults PyPI.

uninstall(packages)

property uv

The uv executable.

which(name)

The path of executable name in this environment, or None.

exception seamm_manager.uv.UvError

Bases: RuntimeError

A uv command failed; the message carries uv’s own output.

seamm_manager.uv.find_uv()

The path to the uv executable, or None.

Looks on PATH first, then where uv’s own installer puts it.

seamm_manager.uv.normalize(name)

The canonical form of a distribution name: lower case, ‘-’ separators.

Module contents

seamm_manager The installer/updater for SEAMM.