losalamos.project#

Project management and filesystem initialization utilities.

This module provides high-level helpers and abstractions for creating, loading, and managing projects organized around a predefined filesystem structure. It defines the core Project class and convenience functions for initializing new projects or restoring existing ones from disk.

The module is designed to evolve as a central coordination layer between project metadata, filesystem layout, and downstream processing workflows.

Functions

archive(sources, folder, name[, ...])

Archive one or more files/folders into a single timestamped zip file.

load_project(project_folder)

Loads a Project from folder

new_project(specs)

Create a new Project from a specification dictionary.

publish(sources, folder, name[, ...])

Archive sources and publish the result under a managed history/latest structure.

Classes

Project([name, alias])

Project filesystem abstraction.
losalamos.project.new_project(specs)[source]#

Create a new Project from a specification dictionary.

Danger

This method overwrites all existing default files.

Parameters:

specs (dict) –

Dictionary containing project specifications.

Required keys:

  • folder_base (str): Path where the project folder will be created.

  • name (str): Name of the project.

Optional keys:

  • alias (str): Alternative identifier. Defaults to None.

  • source (str): Source reference. Defaults to empty string.

  • description (str): Project description. Defaults to empty string.

Raises:

ValueError – If any required key is missing.

Returns:

A new :class:`losalamos.Project instance initialized with the given specifications.

Return type:

losalamos.Project

Script example
import losalamos

# [CHANGE THIS] setup specs dictionary
project_specs = {
    "folder_base": "C:/to/losalamos", # change this path
    "name": "newProject",
    "alias": "NPrj",
    "source": "Me",
    "description": "Just a test"
}

pj = losalamos.new_project(specs=project_specs)
losalamos.project.load_project(project_folder)[source]#

Loads a Project from folder

Parameters:

project_folder (str or Path) – path to project root folder

Returns:

A new :class:`losalamos.Project instance.

Return type:

losalamos.Project

Script example

Load an existing losalamos.Project

# import the package
import losalamos

# get project instance
pj = losalamos.load_project(project_folder="path/to/project/folder")
losalamos.project.archive(sources: str | Path | List[str | Path], folder: str | Path, name: str, ignore_subfolders: bool = False, ignore_names: List[str] | None = None, ignore_patterns: List[str] | None = None) → Path[source]#

Archive one or more files/folders into a single timestamped zip file.

Sources are merged into a shared tree at the zip root rather than being namespaced under separate top-level folders — equivalent to pasting each source folder into the same destination one after another. Same-named subfolders combine their contents non-destructively. A file present in only one source appears once in the result; a relative path present in more than one source raises an error rather than silently overwriting.

Parameters:

  • sources (str, pathlib.Path, or list) – A single path or a list of paths (files and/or folders) to merge and include.

  • folder (str or pathlib.Path) – Target folder where the zip file will be written. Must already exist.

  • name (str) – Base name for the archive (timestamp is appended).

  • ignore_subfolders (bool) – If True, only the top-level files of each source are archived; all subfolders (and their contents) are skipped. Applied independently per source.

  • ignore_names (list of str or None) – Exact folder or file names to exclude, anywhere in the tree (e.g. ["cache", "settings.txt"]). File names must include their extension.

  • ignore_patterns (list of str or None) – Glob-style patterns (* syntax) matched against the filename only (not the full path), e.g. ["*.tmp", "~*"]. Folders are matched the same way by their folder name and, if matched, their entire contents are excluded.

Raises:

  • NotADirectoryError – If folder does not exist as a directory.

  • FileNotFoundError – If any path in sources does not exist.

  • FileExistsError – If two sources resolve to the same relative path in the merged tree (conflicting file).

Returns:

Absolute path to the created zip file.

Return type:

pathlib.Path

losalamos.project.publish(sources: str | Path | List[str | Path], folder: str | Path, name: str, ignore_subfolders: bool = False, ignore_names: List[str] | None = None, ignore_patterns: List[str] | None = None) → Path[source]#

Archive sources and publish the result under a managed history/latest structure.

Builds (or reuses) a folder layout at folder/name/ containing two subfolders, history and latest. The new archive is built directly into latest first; only after it is successfully created is the previously-existing zip (if any) moved into history. This ordering ensures that if archiving fails, latest still holds the last good publish rather than being left empty or having prematurely rotated a valid zip away. Each zip keeps its own timestamped filename from archive(), so nothing is overwritten on rotation.

Parameters:

  • sources (str, pathlib.Path, or list) – A single path or a list of paths (files and/or folders) to merge and archive. See archive().

  • folder (str or pathlib.Path) – Output archive main folder. The managed structure is created at folder/name/. Must already exist.

  • name (str) – Base name for the archive and the managed subfolder under folder.

  • ignore_subfolders (bool) – See archive().

  • ignore_names (list of str or None) – See archive().

  • ignore_patterns (list of str or None) – See archive().

Raises:

  • NotADirectoryError – If folder does not exist as a directory.

  • FileNotFoundError – If any path in sources does not exist.

  • FileExistsError – If two sources resolve to the same relative path in the merged tree (conflicting file).

Returns:

Absolute path to the newly published zip file inside latest.

Return type:

pathlib.Path

class losalamos.project.Project(name='LosAlamosProject', alias='LAProj')[source]#

Bases: FileSys

Project filesystem abstraction.

This class represents a project rooted in a filesystem structure and extends losalamos.root.FileSys. It initializes and manages project metadata and default folder definitions.

load_data()[source]#

Initialize internal project data.

Creates a dataframe describing the default project folder structure based on SUBFOLDERS and assigns it to self.data.

publish(targets, prefix, output_folder=None, surface=False)[source]#

Publish a versioned snapshot of selected directories to a managed output location.

Parameters:

  • targets (list) – A list of directory paths to be included in the snapshot.

  • prefix (str) – The string prefix used for naming the generated archive file.

  • output_folder (pathlib.Path) – [optional] The destination directory for the published archives.

  • surface (bool) – If True, target folders are placed at the zip root instead of preserving project subfolder structure.

Returns:

A dictionary containing the publication status, the resulting path, and metadata.

Return type:

dict

Note

The function performs directory validation, checks for publish frequency constraints based on self.publish_delta, and handles the rotation of the previous ‘latest’ archive into a history folder before promoting the new build.