types(workspace-imports) Example typings via NotRequried

[tony]

Summary by Sourcery

Add example typings for workspace imports by introducing detailed TypedDict schemas and updating importers to reference the new workspace configuration types

Enhancements:

• Define comprehensive TypedDict schemas for shell commands, panes, windows, and workspace configuration using NotRequired for optional fields
• Introduce union types for shell command and pane values to capture both simple and detailed configurations
• Annotate importer functions to reference the WorkspaceConfig type under TYPE_CHECKING and update docstrings to indicate the returned dict conforms to WorkspaceConfig

[sourcery-ai]

Reviewer's Guide

This PR enriches the workspace-imports typing by introducing comprehensive TypedDict definitions with NotRequired for optional fields and updates importer functions to reference the new WorkspaceConfig via TYPE_CHECKING, inline comments, and enhanced docstrings.

Class Diagram of New Tmuxp Configuration Types

classDiagram
    class ShellCommandConfig {
        +cmd: str
        +enter: bool (optional)
        +suppress_history: bool (optional)
    }
    class PaneConfig {
        +shell_command: ShellCommandValue (optional)
        +shell_command_before: ShellCommandValue (optional)
        +start_directory: str (optional)
        +environment: dict[str, str] (optional)
        +focus: str | bool (optional)
        +suppress_history: bool (optional)
    }
    class WindowConfig {
        +window_name: str
        +start_directory: str (optional)
        +shell_command_before: ShellCommandValue (optional)
        +layout: str (optional)
        +options: dict[str, Any] (optional)
        +options_after: dict[str, Any] (optional)
        +environment: dict[str, str] (optional)
        +focus: str | bool (optional)
        +suppress_history: bool (optional)
        +panes: list[PaneValue] (optional)
    }
    class WorkspaceConfig {
        +session_name: str | None
        +start_directory: str (optional)
        +before_script: str (optional)
        +shell_command_before: ShellCommandValue (optional)
        +shell_command: ShellCommandValue (optional)
        +environment: dict[str, str] (optional)
        +global_options: dict[str, Any] (optional)
        +options: dict[str, Any] (optional)
        +config: str (optional)
        +socket_name: str (optional)
        +plugins: list[str | PluginConfigSchema] (optional)
        +suppress_history: bool (optional)
        +windows: list[WindowConfig]
    }
    class PluginConfigSchema {
        +plugin_name: str
        +tmux_min_version: str (optional)
        +tmux_max_version: str (optional)
        +tmux_version_incompatible: list[str] (optional)
        +tmuxp_min_version: str (optional)
        +tmuxp_max_version: str (optional)
        +tmuxp_version_incompatible: list[str] (optional)
    }

    WorkspaceConfig "1" *-- "0..*" WindowConfig : windows
    WorkspaceConfig "1" o-- "0..*" PluginConfigSchema : plugins
    WindowConfig "1" *-- "0..*" PaneConfig : panes (via PaneValue)
    PaneConfig ..> ShellCommandConfig : uses (via ShellCommandValue)
    WindowConfig ..> ShellCommandConfig : uses (via ShellCommandValue)
    WorkspaceConfig ..> ShellCommandConfig : uses (via ShellCommandValue)

Loading

File-Level Changes

Change	Details	Files
Define detailed configuration types using TypedDict and NotRequired	Added ShellCommandConfig TypedDict with NotRequired flags Introduced PaneConfig and WindowConfig TypedDicts marked total=False Created WorkspaceConfig TypedDict for complete workspace structure Defined union aliases ShellCommandValue and PaneValue for flexible typing	src/tmuxp/_internal/types.py
Enhance importer modules with type hints and documentation	Wrapped WorkspaceConfig import in a TYPE_CHECKING guard Augmented function docstrings with Returns section referencing WorkspaceConfig Annotated tmuxp_workspace dict with inline comment noting WorkspaceConfig conformance	src/tmuxp/workspace/importers.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @tony - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion: Annotate tmuxp_workspace with WorkspaceConfig type

Since WorkspaceConfig is already imported under TYPE_CHECKING, use it to annotate tmuxp_workspace and update the function's return type for better type safety.

Suggested change

	Returns
	-------
	dict
	A dictionary conforming to WorkspaceConfig structure.
	"""
	tmuxp_workspace: dict[str, t.Any] = {}
	tmuxp_workspace: dict[str, t.Any] = {} # Will conform to WorkspaceConfig at the end
	from tmuxp.types import WorkspaceConfig
	def import_tmuxinator(workspace_dict: dict[str, t.Any]) -> WorkspaceConfig:
	"""Return tmuxp workspace from a `tmuxinator`_ yaml workspace.
	Returns
	-------
	WorkspaceConfig
	A dictionary conforming to WorkspaceConfig structure.
	"""
	tmuxp_workspace: WorkspaceConfig = {} # Will conform to WorkspaceConfig at the end