# tmuxp.workspace.builder.ClassicWorkspaceBuilder

- **Module:** tmuxp.workspace.builder
- **Package:** tmuxp
- **Language:** Python
- **Kind:** class
- **Source:** https://github.com/tmux-python/tmuxp/blob/153acdf6ff1268b14d3d03ed488f545a7123c8f1/src/tmuxp/workspace/builder/classic.py#L115
- **Page:** https://libtmux.org/en/py/latest/workspace/reference/tmuxp-workspace-builder-classicworkspacebuilder/

Load workspace from workspace :class:`dict` object.

Build tmux workspace from a configuration. Creates and names windows, sets options,
splits windows into panes.

## Example

```python
>>> import yaml
```

## Example

```python
>>> session_config = yaml.load('''
...     session_name: sample workspace
...     start_directory: '~'
...     windows:
...     - window_name: editor
...       layout: main-vertical
...       panes:
...       - shell_command:
...         - cmd: vim
...       - shell_command:
...         - cmd: echo "hey"
...
...     - window_name: logging
...       panes:
...       - shell_command:
...         - cmd: tail | echo 'hi'
...
...     - window_name: test
...       panes:
...       - shell_command:
...         - cmd: htop
... ''', Loader=yaml.Loader)
```

## Example

```python
>>> builder = ClassicWorkspaceBuilder(session_config=session_config, server=server)
```

## Example

**New session:**

```python
>>> builder.build()
```

## Example

```python
>>> new_session = builder.session
```

## Example

```python
>>> new_session.name == 'sample workspace'
True
```

## Example

```python
>>> len(new_session.windows)
3
```

## Example

```python
>>> sorted([window.name for window in new_session.windows])
['editor', 'logging', 'test']
```

## Example

**Existing session:**

```python
>>> len(session.windows)
1
```

## Example

```python
>>> builder.build(session=session)
```

## Example

_Caveat:_ Preserves old session name:

```python
>>> session.name == 'sample workspace'
False
```

## Example

```python
>>> len(session.windows)
3
```

## Example

```python
>>> sorted([window.name for window in session.windows])
['editor', 'logging', 'test']
```

## Example

**Progress callback:**

```python
>>> calls: list[str] = []
>>> progress_cfg = {
...     "session_name": "progress-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=progress_cfg,
...     server=server,
...     on_progress=calls.append,
... )
>>> builder.build()
>>> "Workspace built" in calls
True
```

## Example

**Before-script hook:**

```python
>>> hook_calls: list[bool] = []
>>> no_script_cfg = {
...     "session_name": "hook-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=no_script_cfg,
...     server=server,
...     on_before_script=lambda: hook_calls.append(True),
... )
>>> builder.build()
>>> hook_calls  # no before_script in config, callback not fired
[]
```

## Example

**Script output hook:**

```python
>>> script_lines: list[str] = []
>>> no_script_cfg2 = {
...     "session_name": "script-output-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=no_script_cfg2,
...     server=server,
...     on_script_output=script_lines.append,
... )
>>> builder.build()
>>> script_lines  # no before_script in config, callback not fired
[]
```

## Example

**Build events hook:**

```python
>>> events: list[dict] = []
>>> event_cfg = {
...     "session_name": "events-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=event_cfg,
...     server=server,
...     on_build_event=events.append,
... )
>>> builder.build()
>>> [e["event"] for e in events]
['session_created', 'window_started', 'pane_creating',
 'window_done', 'workspace_built']
>>> next(e for e in events if e["event"] == "session_created")["session_pane_total"]
1
```

## Example

**Build events with before_script:** ``before_script_started`` fires before the script runs; ``before_script_done`` fires in ``finally`` (success or failure).

```python
>>> script_events: list[dict] = []
>>> script_event_cfg = {
...     "session_name": "script-events-demo",
...     "before_script": "echo hello",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=script_event_cfg,
...     server=server,
...     on_build_event=script_events.append,
... )
>>> builder.build()
>>> event_names = [e["event"] for e in script_events]
>>> "before_script_started" in event_names
True
>>> "before_script_done" in event_names
True
>>> bs_start = event_names.index("before_script_started")
>>> bs_done = event_names.index("before_script_done")
>>> win_start = event_names.index("window_started")
>>> bs_start < bs_done < win_start
True
```

## Members

- `server` (attribute)
- `session_name` (attribute)
- `on_progress` (attribute)
- `on_before_script` (attribute)
- `on_script_output` (attribute)
- `on_build_event` (attribute)
- `__init__` (method): Initialize workspace loading.
- `session` (property): Return tmux session using in workspace builder session.
- `session_exists` (method): Return true if tmux session already exists.
- `build` (method): Build tmux workspace in session.
- `iter_create_windows` (method): Return :class:`libtmux.Window` iterating through session config dict.
- `iter_create_panes` (method): Return :class:`libtmux.Pane` iterating through window config dict.
- `config_after_window` (method): Actions to apply to window after window and pane finished.
- `find_current_attached_session` (method): Return current attached session.
- `first_window_pass` (method): Return True first window, used when iterating session windows.