# Changelog

To install the unreleased libtmux version, see [developmental releases](https://libtmux.git-pull.com/quickstart.html#developmental-releases).

[pip](https://pip.pypa.io/en/stable/):

```console
$ pip install --user --upgrade --pre libtmux
```

## libtmux 0.21.x (unreleased)

- _Notes on upcoming releases will be added here_

<!-- Maintainers and contributors: Insert change notes for the next release above -->

## libtmux 0.20.0 (2023-01-15)

### What's new

- Server.new_session: Accept `x` and `y`, thanks
  @rockandska (#469)
- New test fixture: `session_params`. The dict is used direclty in the `session`
  pytest fixture (#470)

## libtmux 0.19.1 (2022-01-07)

### Fixes

- `Window.set_window_option()`: Remove `.refresh()` (#467)

  See also: https://github.com/tmux-python/tmuxp/issues/860

## libtmux 0.19.0 (2022-01-07)

### New features

- `pane.capture_pane()` learned to accept `start` and `end` line numbers (#465)

## libtmux 0.18.3 (2023-01-07)

### Improvement

- `fetch_objs` now raises `ObjectDoesNotExist` with detailed information on
  lookup that failed (#466)

## libtmux 0.18.2 (2022-12-30)

### Fixes

- Server: Launching of new session with default socket (#857)

## libtmux 0.18.1 (2022-12-28)

### Fixes

- Window.panes: Fix docstring
- Remove unused code documentation

## libtmux 0.18.0 (2022-12-27)

### Breaking

- Server: Add `__repr__` and set `socket_path` if none set.

  Before (0.17 and below):

  ```python
  <libtmux.server.Server object at ...>
  ```

  New `__repr__` (0.18+):

  ```python
  Server(socket_name=test)
  ```

  ```python
  Server(socket_path=/tmp/tmux-1000/default)
  ```

## libtmux 0.17.2 (2022-12-27)

- Server: Move `_list_panes` and `_update_panes` to deprecated

## libtmux 0.17.1 (2022-12-27)

### Fixes

- Documentation fixes
- Add deprecation warning to `Server.children`, `Session.children`,
  `Window.children`.

## libtmux 0.17.0 (2022-12-26)

### Breaking changes (#426)

- Finding objects / relations

  - 0.16 and below: `session._windows()`, `session.list_windows()`, etc.

    0.17 and after: {attr}`session.windows <libtmux.Session.windows>`

  - 0.16 and below: `session.find_where({'window_name': my_window})`

    0.17 and after: {meth}`session.windows.get(window_name=my_window, default=None) <libtmux.Session.windows>`

    - If not found and not `default`, raises {exc}`~libtmux._internal.query_list.ObjectDoesNotExist`
    - If multiple objects found, raises {exc}`~libtmux._internal.query_list.MultipleObjectsReturned`

  - 0.16 and below: `session.where({'window_name': my_window})`

    0.17 and after: {meth}`session.windows.filter(window_name=my_window) <libtmux.Session.windows>`

- Accessing attributes

  - 0.16 and below: `window['id']`

    0.17 and after: `window.id`

  - 0.16 and below: `window.get('id')`

    0.17 and after: `window.id`

  - 0.16 and below: `window.get('id', None)`

    0.17 and after: `getattr(window, 'id', None)`

### New features

#### Detect if server active (#448)

- `Server.is_alive()`
- `Server.raise_if_dead()`

### Internal

- Remove unused `sphinx-click` development dependency

## libtmux 0.16.1 (2022-12-12)

### Fixes

- Remove reliance on `packaging.version.Version` (#461)

  This is too critical of a package to pin a dependency as it may interfere with other packages the user relies on. In addition, libtmux doesn't need strict compatibility with `packaging`.

## libtmux 0.16.0 (2022-12-10)

### Breaking changes

- Fix `distutils` warning, vendorize `LegacyVersion` (#351)

  Removal of reliancy on `distutils.version.LooseVersion`, which does not
  support `tmux(1)` versions like `3.1a`.

  Fixes warning:

  > DeprecationWarning: distutils Version classes are deprecated. Use
  > packaging.version instead.

  The temporary workaround, before 0.16.0 (assuming _setup.cfg_):

  ```ini
  [tool:pytest]
  filterwarnings =
      ignore:.* Use packaging.version.*:DeprecationWarning::
      ignore:The frontend.Option(Parser)? class.*:DeprecationWarning::
  ```

### Features

- `Window.split_window()` and `Session.new_window()` now support an optional
  dictionary of environmental variables, via (#453), credit @zappolowski.

## libtmux 0.15.10 (2022-11-05)

_There will be more improvements over the coming weeks and months to shore up
flakiness across shells and environments._

### Tests

- Compatibility improvement for `test_capture_pane` and `env` (#452), credit:
  @zappolowski!
- Remove more BASHisms from tests (#455)

## libtmux 0.15.9 (2022-10-30)

### Bug fix

- `tmux_cmd()`: Fix raise of TmuxCommandNotFound (#450)

### CI

- Use python 3.11 (#451)

### Packaging

- Add python 3.11 to trove classifiers (#451)

### Development

- Add python 3.11 to asdf and pyenv configurations (#451)

## libtmux 0.15.8 (2022-10-02)

### Bug fix

- `Session.new_window()`: Improve support for `window_name: ''` downstream in tmuxp (#444, credit: @trankchung)

## libtmux 0.15.7 (2022-09-23)

- Move `.coveragerc` -> `pyproject.toml` (#443)

## libtmux 0.15.6 (2022-09-23)

_Maintenance only, no bug fixes or features_

### Packaging

- Remove `MANIFEST.in`

  This is handled by poetry's `include` in pyproject.toml.

## libtmux 0.15.5 (2022-09-23)

_Maintenance only, no bug fixes or features_

### Packaging

- Remove `.tmuxp-before-script.sh` from `.tmuxp.yaml`

## libtmux 0.15.4 (2022-09-21)

### Bug fixes

- Use stable `pytest` API imports where possible to fix issues in downstream
  packaging on Arch (#441, via #442)

### Packaging

- Add `.tmuxp-before-script.sh` (used by `.tmuxp.yaml`) and `conftest.py` to
  source distributoins (#441, via #442)

## libtmux 0.15.3 (2022-09-20)

### Tests / docs

- Examples for pytest plugin (#439)
- Move conftest.py to root level (#440)

  - https://docs.pytest.org/en/stable/deprecations.html#pytest-plugins-in-non-top-level-conftest-files
  - Less conftest.py files
  - We can now run py.test for `README.md` without needing to proxy through
    `docs/index.md`

## libtmux 0.15.2 (2022-09-17)

**Maintenance release, no features or fixes**

### Tests

- pytest plugin: Initial tests (for testing the plugin itself, #423)

### Packaging

- pyproject.toml: Note pytest framework in trove classifiers

### Infrastructure

- CI speedups (#428)

  - Avoid fetching unused apt package
  - Split out release to separate job so the PyPI Upload docker image isn't pulled on normal
    runs

## libtmux 0.15.1 (2022-09-11)

### Packaging

- pyproject.toml: Drop old issues package, remove anther package from grouping

### Documentation

- Cleanup quickstart page

## libtmux 0.15.0 (2022-09-10)

### New features

- Added a [pytest plugin](https://libtmux.git-pull.com/pytest-plugin.html), #411.

### Breaking changes

- Remove `common.which()` in favor of {func}`shutil.which`, Credit:
  @rocksandska, via #407
- Fixes #402: {func}`common.tmux_cmd` will only strip _trailing_ empty lines. Before this change,
  all empty lines were filtered out. This will lead to a more accurate behavior when using
  {meth}`Pane.capture_pane`. Credit: @rockandska, via #405.
- Source files for `libtmux` modules moved to `src/`, via #414.

### Development

- Add [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear) (#408)
- Add [flake8-comprehensions](https://github.com/adamchainz/flake8-comprehensions) (#409)

### Tests

- Test doctests in documentation via
  [pytest-doctest-docutils](https://gp-libs.git-pull.com/doctest/pytest.html) (#410)

### Documentation

- Examples updated for correctness, #412 (cherry-picked from #410)
- Render changelog in [linkify_issues](https://gp-libs.git-pull.com/linkify_issues/) (#410)
- Fix Table of contents rendering with sphinx autodoc with
  [sphinx_toctree_autodoc_fix](https://gp-libs.git-pull.com/sphinx_toctree_autodoc_fix/) (#410)

## libtmux 0.14.2 (2022-08-17)

### Fixes

- {meth}`Server.new_session` _really_ works without `session_name`, #401 fixes
  #399. Improved tests and doctests added.

## libtmux 0.14.1 (2022-08-17)

### Fixes

- {meth}`Server.new_session` works without `session_name`, #400 fixes
  #399

  _This still passed `None` to the session name, this was fixed in v0.14.2._

## libtmux 0.14.0 (2022-08-05)

### Breaking changes

- {meth}`Pane.send_keys`: `suppress_history` default value changed from `True` to
  `False`, #395

### Tests and docs

- Initial [doctests] examples stubbed out #394

  [doctests]: https://docs.python.org/3/library/doctest.html

- Fix bug in `temp_window()` context manager, #394
- Pytest configuration `conftest.py` moved to `libtmux/conftest.py`, so doctest can
  detect the fixtures #394

## libtmux 0.13.0 (2022-08-05)

### What's new

- **Improved typings**

  Now [`mypy --strict`] compliant (#383)

  Smaller touchups from #392

  [`mypy --strict`]: https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-strict

### Breaking changes

- Deprecated individual item lookups (#390)

  - Removed key lookups from {meth}`libtmux.common.EnvironmentMixin.show_environment`

    Only `EnvironmentMixin.show_environment()` (without an argument) exists, and
    it still returns a `dict`.

  - Add key lookups via {meth}`libtmux.common.EnvironmentMixin.getenv`

    ```python
    # Before
    server.show_environment('DISPLAY')

    # After
    server.getenv('DISPLAY')

    # Before
    session.show_environment('DISPLAY')

    # After
    session.getenv('DISPLAY')
    ```

  - Removed key lookups from {meth}`Session.show_options`

    ```python
    session.show_options()  # still returns dict, without an argument

    # Old
    session.show_options('DISPLAY')

    # Now
    session.show_option('DISPLAY')
    ```

  - Removed key lookups from {meth}`Window.show_window_options`

    ```python
    window.show_window_options()  # still returns dict, without an argument

    # Old
    window.show_window_options('DISPLAY')

    # Now
    window.show_window_option('DISPLAY')
    ```

- Remove `libtmux.test.retry()`, deprecated since 0.12.x (#393)

### Development

- Fix incorrect function name `findWhere()` (#391)

## libtmux 0.12.0 (2022-07-13)

### Compatibility

- Brought back python 3.7 and 3.8 support (#375)
- Support for tmux 3.3a

  - Add to CI
  - Bump `TMUX_MAX_VERSION` from 2.4 -> 3.3

    _2.4 to 3.3a already worked, this is just the constant
    being updated._

### Development

- Remove tox and tox-poetry-installer

  This created issues with running poetry while inside the virtualenv.

- Typings: Core relations, e.g. `Pane.window`, `Pane.session`, `Pane.server`, `Window.server` #385

### Documentation

- Renewed logo
- Try out sphinx-autoapi for its table of contents generation (#367)
- Break up API documentations for utilities, exception, and test helpers and
  remove duplicate docs from API page. Server, session, window, and pane docs
  are in the Reference section now.

### Testing

- `retry()`: Add deprecation warning. This will be removed in 0.13.x (#368, #372)
- New function `retry_until()`: Polls a callback function for a set period of time until it returns `True` or times out. By default it will raise {exc}`libtmux.exc.WaitTimeout`, with `raises=False` it will return `False`. Thank you @categulario! (#368, #372)
- #384 Chore: Use absolute modules rather than root-level to avoid cyclic imports.

  ```python
  # Bad / Old
  from libtmux import Server

  # Good / New
  from libtmux.server import Server
  ```

### Internals

- #382 [mypy] support added:

  - Basic mypy tests now pass

## libtmux 0.11.0 (2022-03-10)

### Compatibility

- Python 3.7 and 3.8 returns in 0.12.0

  ~~Final python 3.7 and 3.8 release~~

  ~~Bug fixes and security updates will go to
  [`v0.11.x`](https://github.com/tmux-python/libtmux/tree/v0.11.x)~~

- Internal: Use new separator to split `tmux(1)` formatting information (#289,
  #343)

  The separator is configurable via `LIBTMUX_TMUX_FORMAT_SEPARATOR`. If you ever
  have compatiblity issues in the future let us know which default works best
  across versions.

  Credit: @JonathanRaiman and @jagguli

- Basic type annotations (#359, #361) via @otherJL0

### Development

- Code cleanup (#362) from @otherJL0
- Format with black w/ string normalization. This is a one-time diff (#354)

### Documentation

- Sidebar reorganized into sections
- Added documentation on fetching developmental releases of libtmux

## libtmux 0.10.3 (2022-01-10)

### Packaging

First experimental release using `poetry build` (#347). If you are packaging and run
across any difficulty please see #346.

### Compatibility

- Drop python 3.6 (#344)
- Add python 3.10, though still `packaging.version` issues remain (#344)

  A compat module and version constraints will need to be added for this

### Development

- poetry: 1.1.7 -> 1.1.12 (#344)
- Add `.pre-commit-config.yaml` (#344)

## libtmux 0.10.2 (2021-10-30)

- #324: Update poetry to 1.1
  - CI: Use poetry 1.1.7 and `install-poetry.py` installer
  - Relock poetry.lock at 1.1 (w/ 1.1.7's fix)
- #339 (CI): Lock python at 3.9 to avoid poetry issue with `dataclasses`
- ci: Fix publishing docs (similar to #339)
- #341 #342: `Server.attached_sessions()` now supports multiple attached sessions.

  Remove attached sessions limitation to not detect multiple attached clients,
  thank you @timoses

## libtmux 0.10.1 (2021-06-16)

- Update `Window.select_window()` for #271

## libtmux 0.10.0 (2021-06-16)

- #321: Convert to markdown
- #271: Fix {}`select_window()` by providing the session ID as
  argument to {}`-t`. Thanks @Flowdalic
- Drop python 3.5 support

## libtmux 0.9.0 (2021-06-14)

Python 2.7 support dropped.

- #306: chore: Remove python 2.7 support
- #314: chore: Python 3.x syntax tweaks
- #312: ci: Add tmux 3.2a to CI
- chore: Update black to [21.6b0](https://github.com/psf/black/blob/21.6b0/CHANGES.md#216b0)
- #271: Fix select_window() by providing the session ID as
  argument to -t.

## libtmux 0.8.5 (2020-10-25)

- #297: Enchance subprocess interaction std[in|out|err]. Needed
  for interact with big buffer, fixes #251, thank you
  @gil-obradors!
- #303 Add `common.get_libtmux_version` which gives the tmux
  version as a loose constraint. Fix linking to terms inside docs, and
  duplicate description of module which sphinx warned about in api.rst.
- #266 Fix issue on local tests where env variables would cause
  show-environment to pause tests indefinitely.

## libtmux 0.8.4 (2020-10-25)

- #234: `Window.split_window`: Allow passing `percent`, Thank
  you @jinankjain!
- #289: Fix warning due to invalid escape sequences, Thank you
  @tirkarthi!
- #295: Publish docs via our own action
- #295: Move more packaging over to poetry, though we'll keep
  setup.py for the moment to ensure compatibility package maintainers.
- #295: New development instructions
- #295: Move doc/ to docs/
- #296: CI: Test python 2.7, cache python packages, prevent running
  internal PRs twice

## libtmux 0.8.3 (2020-08-16)

- #278: Fix Python deprecation warnings, thanks @d1618033

  Also thanks Flowdalic for a similar PR at #294

- Add `project_urls` to setup.py
- #293 Move from Pipfile to poetry
- Fix show_option test in tmux 3.0
- Clean up handle_option_error comments
- Move CI to a GitHub action

## libtmux 0.8.2 (2019-06-02)

- CHANGES updated to plain reStructuredText
- Add `project_urls` to setup.py for pypi.
- Looser Pipfile versions, add Pipfile.lock

## libtmux 0.8.1 (2019-01-26)

- #117 Fix issue with renaming clients with tmux 2.7 on BSD/macOS
  machines.
- #121 Support `literal=True` (`-l`) in `Pane.send_keys`
  from @ritiek
- #131 Fix for unicode commands in Python 2, thanks @myw
- #172 Support for next-X.Y versions from @sloria
- #120 `capture_pane` support for `Pane`
- #119 `display_message` support for `Pane`
- Sort imports with isort
- Add sphinxcontrib-napoleon package for documentation
- Move docstrings over to numpy's style

## libtmux 0.8.0 (2018-03-11)

- #46 Change license from BSD to MIT
- Move to new organization, tmux-python
- Support package updates to pytest, sphinx, etc.
- Travis/CI: Limit tests to Python 2.7 and 3.6 (removed 3.3 to 3.5)
- Travis/CI: Update pypy veersions
- #103 `Server.new_session` learned how to run commands in
  window on session start, thanks @grimpy!
- #68 Make Server.has_session() use returncode, thanks
  @jlargentaye! This should make `has_session` more robust.

## libtmux 0.7.8 (2018-03-04)

- Port `retry` function from tmuxp
  (<https://github.com/tmux-python/tmuxp/issues/354>)

## libtmux 0.7.7 (2017-11-10)

- Don't add -x/-y in tmux >= 2.6 if running tmuxp from inside
  client.

## libtmux 0.7.6 (2017-11-09)

- Allow `Window.select_layout` with no args
- Fix test where `bell-` was no longer ambiguous as of tmux 2.6

## libtmux 0.7.5 (2017-10-07)

- Hotfix to support tmux 2.6 session creation

## libtmux 0.7.4 (2017-08-19)

- #65 Add session id to commands, thanks [@askedrelic][@askedrelic]

## libtmux 0.7.3 (2017-05-29)

- Exact matches only supported on 2.1 and up

## libtmux 0.7.2 (2017-05-29)

- Support exact matching in `Server.has_session`

## libtmux 0.7.1 (2017-04-28)

- #37 Improve support for formatted options like
  `pane-border-status`. Thanks @kaushalmodi.

## libtmux 0.7.0 (2017-04-27)

- Support for python 2.6 dropped. New minimum version is 2.7
- Add support for tmux 2.4, pypy and pypy3
- Overhaul error handling when setting and showing options

  - Added {}`handle_option_error` for handling option errors
  - Added {exc}`libtmux.exc.OptionError` base exception
  - Added {exc}`libtmux.exc.InvalidOption` and {}`libtmux.exc.AmbiguousOption`
  - {exc}`libtmux.exc.UnknownOption` now extends {exc}`libtmux.exc.OptionError`

- Overhaul version checking

  - `has_version` has been renamed to `get_version`
  - `get_version` will return tmux built from git master as the latest version supported by the libtmux version with `-master` at the end, e.g. `2.4-master`
  - `get_version` will return tmux on openbsd base system as the latest version supported by the libtmux version with `-openbsd` at the end, e.g. `2.4-openbsd`
  - `has_required_tmux_version` has been renamed to `has_minimum_version`
  - added `has_gt_version`, `has_gte_version`, `has_lt_version`, `has_lte_version`,

- Fixed up documentation in some session methods
- Added pydoc exception info to option methods in window and sessions.
- Added `TMUX_MIN_VERSION` and `TMUX_MAX_VERSION`

## libtmux 0.6.5 (2017-04-02)

- Fix `which` command
- Add `TmuxCommandNotFound` exception
- Add `tmux_search_paths` and `append_env_path` kwargs to
  `tmux_cmd`.

## libtmux 0.6.4 (2017-03-25)

- #32 support for OpenBSD's tmux

## libtmux 0.6.3 (2017-02-08)

- #25 support for working with tmux `master`, thanks @sloria.

## libtmux 0.6.2 (2017-01-19)

- #197 use {}`LooseVersion` instead of {}`StrictVersion` for version
  checks. Thanks @minijackson.
- Pin packages with pyup.io
- #21 Readme fix from @huwenchao.

## libtmux 0.6.1 (2016-12-20)

- #18 Fix logger, courtesy of @geekli
- #19 Add support for `start_directory` in new sessions and
  panes, courtesy of @gandelman-a.
- Fix tests and add official support for 2.3

## libtmux 0.6.0 (2016-09-16)

- Raise exception for invalid session names. tmux does not
  allow names that are empty, contain periods or colons.
- Remove unused `target_sesssion` param in
  `Server.attach_session` and `Server.switch_client`.

## libtmux 0.5.1 (2016-08-18)

- #12 - fix logger message when tmux doesn't exist in `PATH`

## libtmux 0.5 (2016-06-15)

- #8 new exception `UnknownOption`
- #8 return `None` for options that are valid tmux options,
  but unset at that scope.
- #6 major documentation overhaul

## libtmux 0.4.1 (2016-05-23)

- update `which()` to find tmux via `os.environ['PATH']`.
  <https://redd.it/4laeut>

## libtmux 0.4.0 (2016-05-23)

- attributes for formatters are now accessible via
  `Session`, `Window` and `Pane` objects. `session.name`
  is equivalent to `session.get('session_name')`, you can do the
  same with other properties in `_info`. `window.name`,
  `pane.current_path`, `session.id`, `window.id`, `pane.id`,
  `session.index`, `window.index`, `pane.index`, etc.
- `attached_sessions`, `attached_window` and
  `attached_pane` are now properties.
- `_TMUX` metadata object changed to `_info`.
- `.findWhere()` is now `find_where`.
- README and usage fixes

## libtmux 0.3.0 (2016-05-23)

- switch to pytest

## libtmux 0.1.0 (2016-05-22)

- libtmux forked from [tmuxp][tmuxp].

[tmuxp]: https://github.com/tmux-python/tmuxp
[@askedrelic]: https://github.com/askedrelic

<!---
# vim: set filetype=markdown:
-->
