.windsurfrules

# libtmux Python Project Rules

<project_stack>
- uv - Python package management and virtual environments
- ruff - Fast Python linter and formatter
- py.test - Testing framework
  - pytest-watcher - Continuous test runner
- mypy - Static type checking
- doctest - Testing code examples in documentation
</project_stack>

<coding_style>
- Use a consistent coding style throughout the project
- Format code with ruff before committing
- Run linting and type checking before finalizing changes
- Verify tests pass after each significant change
</coding_style>

<python_docstrings>
- Use reStructuredText format for all docstrings in src/**/*.py files
- Keep the main description on the first line after the opening `"""`
- Use NumPy docstyle for parameter and return value documentation
- Format docstrings as follows:
  ```python
  """Short description of the function or class.

  Detailed description using reStructuredText format.

  Parameters
  ----------
  param1 : type
      Description of param1
  param2 : type
      Description of param2

  Returns
  -------
  type
      Description of return value
  """
  ```
</python_docstrings>

<python_doctests>
- Use narrative descriptions for test sections rather than inline comments
- Format doctests as follows:
  ```python
  """
  Examples
  --------
  Create an instance:

  >>> obj = ExampleClass()
  
  Verify a property:
  
  >>> obj.property
  'expected value'
  """
  ```
- Add blank lines between test sections for improved readability
- Keep doctests simple and focused on demonstrating usage
- Move complex examples to dedicated test files at tests/examples/<path_to_module>/test_<example>.py
- Utilize pytest fixtures via doctest_namespace for complex scenarios
</python_doctests>

<testing_practices>
- Run tests with `uv run py.test` before committing changes
- Use pytest-watcher for continuous testing: `uv run ptw . --now --doctest-modules`
- Fix any test failures before proceeding with additional changes
</testing_practices>

<git_workflow>
- Make atomic commits with conventional commit messages
- Start with an initial commit of functional changes
- Follow with separate commits for formatting, linting, and type checking fixes
</git_workflow>

<git_commit_standards>
- Use the following commit message format:
  ```
  Component/File(commit-type[Subcomponent/method]): Concise description

  why: Explanation of necessity or impact.
  what:
  - Specific technical changes made
  - Focused on a single topic

  refs: #issue-number, breaking changes, or relevant links
  ```

- Common commit types:
  - **feat**: New features or enhancements
  - **fix**: Bug fixes
  - **refactor**: Code restructuring without functional change
  - **docs**: Documentation updates
  - **chore**: Maintenance (dependencies, tooling, config)
  - **test**: Test-related updates
  - **style**: Code style and formatting

- Prefix Python package changes with:
  - `py(deps):` for standard packages
  - `py(deps[dev]):` for development packages
  - `py(deps[extra]):` for extras/sub-packages

- General guidelines:
  - Subject line: Maximum 50 characters
  - Body lines: Maximum 72 characters
  - Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
  - Limit to one topic per commit
  - Separate subject from body with a blank line
  - Mark breaking changes clearly: `BREAKING:`
</git_commit_standards>

<pytest_testing_guidelines>
- Use fixtures from conftest.py instead of monkeypatch and MagicMock when available
- For libtmux tests, use these provided fixtures for fast, efficient tmux resource management:
  - `server`: Creates a temporary tmux server with isolated socket
  - `session`: Creates a temporary tmux session in the server
  - `window`: Creates a temporary tmux window in the session
  - `pane`: Creates a temporary tmux pane in the pane
  - `TestServer`: Factory for creating multiple independent servers with unique socket names
- Example usage with server fixture:
  ```python
  def test_something_with_server(server):
      # server is already running with proper configuration
      my_session = server.new_session("test-session")
      assert server.is_alive()
  ```
- Example usage with session fixture:
  ```python
  def test_something_with_session(session):
      # session is already created and configured
      new_window = session.new_window("test-window")
      assert new_window in session.windows
  ```
- Customize session parameters by overriding the session_params fixture:
  ```python
  @pytest.fixture
  def session_params():
      return {
          'x': 800,
          'y': 600,
          'window_name': 'custom-window'
      }
  ```
- Benefits of using libtmux fixtures:
  - No need to manually set up and tear down tmux infrastructure
  - Tests run in isolated tmux environments
  - Faster test execution
  - Reliable test environment with predictable configuration
- Document in test docstrings why standard fixtures weren't used for exceptional cases
- Use tmp_path (pathlib.Path) fixture over Python's tempfile
- Use monkeypatch fixture over unittest.mock
</pytest_testing_guidelines>

<import_guidelines>
- Prefer namespace imports over importing specific symbols
- Import modules and access attributes through the namespace:
  - Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
  - This applies to standard library modules like pathlib, os, and similar cases
- For typing, use `import typing as t` and access via the namespace:
  - Access typing elements as `t.NamedTuple`, `t.TypedDict`, etc.
  - Note primitive types like unions can be done via `|` pipes
  - Primitive types like list and dict can be done via `list` and `dict` directly
- Benefits of namespace imports:
  - Improves code readability by making the source of symbols clear
  - Reduces potential naming conflicts
  - Makes import statements more maintainable
</import_guidelines>