pestifer.core.examplemanager module

A module for managing example input files in pestifer. This module provides the ExampleManager class, which allows users to check out example YAML files, report the list of examples, and manage example resources.

ExampleManager does not directly manage the example documentation, but it relies on the SphinxExampleManager class to handle the documentation side of things.

class pestifer.core.examplemanager.ExampleManager(examples_path: str | Path | None = None, docs_source_path: str | Path | None = None)

Bases: object

A class for managing example YAML input files in pestifer. This class provides methods to check out example YAML files, report the list of examples, and manage example resources. Each example has a root folder that lives in examples_path.

Parameters:

• example_path (str) – The path to the directory containing example root folders.

• docs_path (str) – The path to the directory containing documentation files. This is passed directly to the SphinxExampleManager class. If not provided, the documentation management is not enabled.

append_example(example_id: int, scriptname: str, title: str = '', db_id: str = '', author_name: str = '', author_email: str = '', auxiliary_inputs: list = [], outputs: list = [])

Create a new Example from keyword arguments and add it to the examples list.

Parameters:

• example_id (int) – The unique integer ID of the example.

• scriptname (str) – The name of the example script file to insert. This should be a valid file path since a new Example is created.

• title (str) – A title of the example; if not provided, it is extracted from the script.

• db_id (str) – The structure/sequence database ID associated with the example.

• author_name (str) – The name of the author of the example.

• author_email (str) – The email of the author of the example.

• auxiliary_inputs (list[str]) – A list of auxiliary input files associated with the example.

• outputs (list[str]) – A list of output files associated with the example.

Returns:

The newly created Example object.

Return type:

Example

Raises:

FileNotFoundError – If the example scriptfile does not exist in the CWD.

checkin_example(example: Example, overwrite: bool = False)

Check in an Example instance by copying its YAML file and companion files to the appropriate example folder, which is created if it doesn’t already exist. This will overwrite the existing files. If any file referenced by the example does not exist in the current working directory, a warning is logged but no action taken.

Parameters:

• example (Example) – The Example instance defining the destination folder and files to copy.

• overwrite (bool, optional) – If True, overwrite existing files in the example folder. Default is False.

checkout_example(example_id: int) → Example

Copy example YAML file and associated companion files by example ID to the current working directory.

Parameters:

example_id (int) – The ID of the example to check out.

Returns:

The example that was checked out.

Return type:

Example

Raises:

• IndexError – If the index is out of range for the examples list.

• FileNotFoundError – If the example YAML file does not exist in the specified path.

clone(newpath: str | Path) → ExampleManager

Spawn a new ExampleManager instance rooted at a directory different from the current ExampleManager’s path (newpath). The new ExampleManager instance will contain copies of all examples in the current ExampleManager’s examples list.

Parameters:

subpath (str or Path) – The subdirectory path relative to the current ExampleManager’s path.

Returns:

A new ExampleManager instance rooted at the specified subdirectory.

Return type:

ExampleManager

copy_from(other: ExampleManager, example: Example)

Copy an example from another ExampleManager instance to this instance.

Parameters:

• other (ExampleManager) – The other ExampleManager instance to copy the example from.

• example (Example) – The Example instance to copy.

• overwrite (bool, optional) – If True, overwrite existing files in the example folder. Default is False.

delete_example(example_id: int)

Delete an example from the examples list by its ID and returns the instance.

Parameters:

example_id (int) – The example ID of the example to delete.

Returns:

The deleted example instance.

Return type:

Example

Raises:

• IndexError – If the index is out of range for the examples list.

• FileNotFoundError – If the example file does not exist in the specified path.

examplefolderpath(example: Example) → Path

inputspath(example: Example) → Path

new_example_yaml(db_id: str = 'ABCD', build_type: str = 'minimal', outputfilename: str = None, title: str = '')

Generate a new example YAML file based on an existing example template. The id can be a 4-letter PDB ID or an Alphafold/UNIPROT ID starting with “P”. The build_type can be either ‘minimal’ or ‘full’, which determines whether the generated YAML file contains only the psfgen task or all tasks including termination.

Parameters:

• db_id (str, optional) – The ID for the new example YAML file. It can be a 4-letter PDB ID or an Alphafold/UNIPROT ID starting with “P”. Default is ‘ABCD’.

• build_type (str, optional) – The type of build for the new example YAML file. It can be either ‘minimal’ or ‘full’. Default is ‘minimal’.

outputspath(example: Example) → Path

rename_example(example_id: int, new_shortname: str)

Rename an example in the examples list by its ID.

Parameters:

• index (int) – The ID of the example to rename.

• new_shortname (str) – The new short name for the example.

Returns:

The renamed Example object.

Return type:

Example

report_examples(header=False, formatter='{:>7s}  {:>8s}  {:<30s}  {}')

Generate a report of the available examples in the examples list.

Parameters:

• header (bool, optional) – If True, include a header in the report. Default is False.

• formatter (str, optional) – A format string for the report. Default is a string that formats the index, name, and title of each example. Default is r'{:>7s}    {:<30s}    {}'.

Returns:

A report of the available examples in the examples list.

Return type:

str

scriptpath(example: Example) → Path

set_example_author(example_id: int, author_name: str, author_email: str)

Set the author information for an example in the examples list by its ID.

Parameters:

• example_id (int) – The ID of the example to set the author for.

• author_name (str) – The name of the author.

• author_email (str) – The email address of the author.

Returns:

The updated Example object with the new author information.

Return type:

Example

update_example(example_id: int, shortname: str = '', title: str = '', db_id: str = '', author_name: str = '', author_email: str = '', auxiliary_inputs: list = [], outputs: list = [], skip_sphinx: bool = False)

Update an existing example in the examples list by its unique index.

Parameters:

• example_id (int) – The unique ID of the example to update.

• shortname (str) – The short name of the example to update (without extension).

• title (str) – A title of the example; overrides value of ‘title’ in the <name>.yaml if it exists.

• pdbID (str) – The PDB ID (or Alphafold ID) associated with the example; overrides value of ‘id’ or ‘alphafold’ in the <name>.yaml if it exists.

• author_name (str) – The name of the author of the example; overrides the name in the # Author line of <name>.yaml if it exists.

• author_email (str) – The email of the author of the example; overrides the email in the # Author line of <name>.yaml if it exists.

• companion_files (list, optional) – A list of companion files associated with the example; defaults to an empty list.

• skip_sphinx (bool, optional) – If True, skip updating the Sphinx documentation for this example.

Returns:

The updated Example object if the update was successful, or None if the example was not found.

Return type:

Example or None

Raises:

FileNotFoundError – If the example file does not exist at the specified path.