bw2io.backup#

Attributes#

_METADATA_FIELDS

Functions#

_add_project_metadata(→ None)

_extract_single_directory_tarball(→ pathlib.Path)

_remove_project_metadata(→ None)

_restore_project_metadata(→ None)

_rmtree_robust(→ None)

Remove a directory tree, retrying on Windows if files are briefly locked.

backup_data_directory([timestamp, dir_backup])

Backup the Brightway2 data directory to a .tar.gz (compressed tar archive) in a specified directory, or in the user's home directory by default.

backup_project_directory(→ pathlib.Path)

Backup project data directory to a .tar.gz (compressed tar archive) in the user's home directory, or a directory specified by dir_backup.

restore_project_directory(fp[, project_name, ...])

Restore a backed up project data directory from a .tar.gz (compressed tar archive) specified by fp. Choose a custom name, or use the name of the project in the archive. If the project already exists, you must set overwrite_existing to True.

Module Contents#

bw2io.backup._add_project_metadata() → None[source]#
bw2io.backup._extract_single_directory_tarball(filepath: pathlib.Path, output_dir: pathlib.Path) → pathlib.Path[source]#
bw2io.backup._remove_project_metadata() → None[source]#
bw2io.backup._restore_project_metadata() → None[source]#
bw2io.backup._rmtree_robust(path: pathlib.Path) → None[source]#

Remove a directory tree, retrying on Windows if files are briefly locked.

On Windows, SQLite files extracted from a tarball can be transiently locked by the OS (e.g. antivirus scanning) immediately after being written. Retry with exponential backoff before giving up and re-raising.

bw2io.backup.backup_data_directory(timestamp: bool | None = True, dir_backup: str | pathlib.Path | None = None)[source]#

Backup the Brightway2 data directory to a .tar.gz (compressed tar archive) in a specified directory, or in the user’s home directory by default.

The file name is of the form “brightway2-data-backup.{timestamp}.tar.gz”, unless timestamp is False, in which case the file name is “brightway2-data-backup.tar.gz”.

Parameters:

  • timestamp (bool, optional) – If True, append a timestamp to the backup file name.

  • dir_backup (str, Path, optional) – Directory to backup. If None, use the user’s home directory.

Raises:

  • FileNotFoundError – If the backup directory does not exist.

  • PermissionError – If the backup directory is not writable.

Examples

>>> import bw2io
>>> bw2io.bw2setup()
>>> bw2io.backup.backup_data_directory()
Creating backup archive - this could take a few minutes...
bw2io.backup.backup_project_directory(project: str, timestamp: bool | None = True, dir_backup: str | pathlib.Path | None = None) → pathlib.Path[source]#

Backup project data directory to a .tar.gz (compressed tar archive) in the user’s home directory, or a directory specified by dir_backup.

File name is of the form brightway2-project-{project}-backup{timestamp}.tar.gz, unless timestamp is False, in which case the file name is brightway2-project-{project}-backup.tar.gz.

Parameters:

  • project (str) – Name of the project to backup.

  • timestamp (bool, optional) – If True, append a timestamp to the backup file name.

  • dir_backup (str, Path, optional) – Directory to backup. If None, use the default (home)).

Returns:

filepath – pathlib.Path of archive file

Return type:

Path

Raises:

  • ValueError – If the project does not exist.

  • FileNotFoundError – If the backup directory does not exist.

  • PermissionError – If the backup directory is not writable.

See also

bw2io.backup.restore_project_directory

To restore a project directory from a backup.

bw2io.backup.restore_project_directory(fp: str | pathlib.Path, project_name: str | None = None, overwrite_existing: bool | None = False, switch: bool = False)[source]#

Restore a backed up project data directory from a .tar.gz (compressed tar archive) specified by fp. Choose a custom name, or use the name of the project in the archive. If the project already exists, you must set overwrite_existing to True.

Parameters:

  • fp (str, Path) – File path of the project to restore.

  • project_name (str, optional) – Name of new project to create.

  • overwrite_existing (bool, optional)

  • switch (bool, optional.) – Switch to new project after restoring it.

Returns:

project_name – Name of the project that was restored.

Return type:

str, Path

Raises:

  • FileNotFoundError – If the file path does not exist.

  • ValueError – If the project name cannot be found in the archive. If the project exists and overwrite_existing is False.

See also

bw2io.backup.backup_project_directory

To backup a project directory.

bw2io.backup._METADATA_FIELDS[source]#