Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit ea8fc51

Browse filesBrowse files
tonytony
committed
docs/tests: Add server doctest examples
1 parent 3686f3c commit ea8fc51
Copy full SHA for ea8fc51

File tree

Expand file treeCollapse file tree

1 file changed

+118
-69
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+118
-69
lines changed

‎src/libtmux/server.py

Copy file name to clipboardExpand all lines: src/libtmux/server.py
+118-69Lines changed: 118 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,23 @@
77
88
libtmux.server
99
~~~~~~~~~~~~~~
10+
11+
Examples
12+
--------
13+
>>> from libtmux import Server
14+
>>> server = Server() # Create a new server instance
15+
>>> server.is_alive() # Check if tmux server is running
16+
True
17+
>>> # Clean up any existing test session first
18+
>>> if server.has_session("test_session"):
19+
... server.kill_session("test_session")
20+
>>> new_session = server.new_session(session_name="test_session")
21+
>>> new_session.name
22+
'test_session'
23+
>>> server.has_session("test_session")
24+
True
25+
>>> server.kill_session("test_session") # Clean up
26+
Server(socket_path=/tmp/tmux-.../default)
1027
"""
1128

1229
from __future__ import annotations
@@ -359,25 +376,33 @@ def attached_sessions(self) -> list[Session]:
359376
return self.sessions.filter(session_attached__noeq="1")
360377

361378
def has_session(self, target_session: str, exact: bool = True) -> bool:
362-
"""Check if a session with the given name (or pattern) exists.
379+
"""Return True if session exists.
363380
364381
Parameters
365382
----------
366-
target_session
367-
The session name or pattern to check.
368-
exact
369-
Whether to require an exact match (tmux 2.1+). If True, prepends
370-
``=`` to the session name for an exact match.
371-
372-
Raises
373-
------
374-
exc.BadSessionName
375-
If the `target_session` is invalid.
383+
target_session : str
384+
Target session name to check
385+
exact : bool, optional
386+
If True, match the name exactly. Otherwise, match as a pattern.
376387
377-
Returns
378-
-------
379-
bool
380-
True if the session exists, False otherwise.
388+
Examples
389+
--------
390+
>>> server = Server()
391+
>>> # Clean up any existing test session
392+
>>> if server.has_session("test_session"):
393+
... server.kill_session("test_session")
394+
>>> server.new_session(session_name="test_session")
395+
Session($... test_session)
396+
>>> server.has_session("test_session")
397+
True
398+
>>> server.has_session("nonexistent")
399+
False
400+
>>> server.has_session("test_session", exact=True) # Exact match
401+
True
402+
>>> server.has_session("test*", exact=False) # Pattern match
403+
True
404+
>>> server.kill_session("test_session") # Clean up
405+
Server(socket_path=/tmp/tmux-.../default)
381406
"""
382407
session_check_name(target_session)
383408

@@ -409,23 +434,26 @@ def kill(self) -> None:
409434
self.cmd("kill-server")
410435

411436
def kill_session(self, target_session: str | int) -> Server:
412-
"""Kill a specific session on this server.
437+
"""Kill a session by name.
413438
414439
Parameters
415440
----------
416-
target_session
417-
The session name or ID to kill. Note that tmux uses fnmatch(3),
418-
so 'asdf' might also match 'asdfasd'.
441+
target_session : str or int
442+
Name of the session or session ID to kill
419443
420-
Returns
421-
-------
422-
Server
423-
This server object (for chaining).
424-
425-
Raises
426-
------
427-
exc.LibTmuxException
428-
If tmux reports an error (stderr output).
444+
Examples
445+
--------
446+
>>> server = Server()
447+
>>> # Clean up any existing session first
448+
>>> if server.has_session("temp"):
449+
... server.kill_session("temp")
450+
>>> session = server.new_session(session_name="temp")
451+
>>> server.has_session("temp")
452+
True
453+
>>> server.kill_session("temp")
454+
Server(socket_path=/tmp/tmux-.../default)
455+
>>> server.has_session("temp")
456+
False
429457
"""
430458
proc = self.cmd("kill-session", target=target_session)
431459
if proc.stderr:
@@ -487,58 +515,63 @@ def new_session(
487515
*args: t.Any,
488516
**kwargs: t.Any,
489517
) -> Session:
490-
"""Create a new tmux session and return the associated :class:`Session`.
491-
492-
Uses ``-P -F#{session_id}`` to capture the session ID in the output.
518+
"""Create a new session.
493519
494520
Parameters
495521
----------
496522
session_name : str, optional
497-
The name to assign to the new session (``-s`` flag).
523+
Name of the session
498524
kill_session : bool, optional
499-
If True, kills any existing session with the same name.
525+
Kill session if it exists
500526
attach : bool, optional
501-
If True, creates the new session in the foreground (no ``-d`` flag).
527+
Attach to session after creating it
502528
start_directory : str, optional
503-
Working directory for the new session (``-c`` flag).
529+
Working directory for the session
504530
window_name : str, optional
505-
If given, creates the session's first window with this name (``-n``).
531+
Name of the initial window
506532
window_command : str, optional
507-
A shell command to run immediately in the new window; the window
508-
closes when the command exits.
533+
Command to run in the initial window
509534
x : int or "-", optional
510-
Forces the specified width for the new session if detached (``-x``).
535+
Width of new window
511536
y : int or "-", optional
512-
Forces the specified height for the new session if detached (``-y``).
513-
environment : dict of str to str, optional
514-
Environment variables to set for the session (tmux 3.2+).
515-
516-
Returns
517-
-------
518-
Session
519-
The newly created :class:`Session`.
520-
521-
Raises
522-
------
523-
exc.TmuxSessionExists
524-
If a session with the given `session_name` already exists and
525-
`kill_session` is False.
526-
exc.BadSessionName
527-
If `session_name` is invalid.
528-
exc.LibTmuxException
529-
If tmux reports an error (stderr output).
537+
Height of new window
538+
environment : dict, optional
539+
Dictionary of environment variables to set
530540
531541
Examples
532542
--------
533-
Sessions can be created without a session name:
534-
535-
>>> server.new_session()
536-
Session($2 2)
537-
538-
With a session name:
543+
>>> server = Server()
544+
>>> # Clean up any existing sessions first
545+
>>> for name in ["basic", "custom", "env_test"]:
546+
... if server.has_session(name):
547+
... server.kill_session(name)
548+
>>> # Create a basic session
549+
>>> session1 = server.new_session(session_name="basic")
550+
>>> session1.name
551+
'basic'
552+
553+
>>> # Create session with custom window name
554+
>>> session2 = server.new_session(
555+
... session_name="custom",
556+
... window_name="editor"
557+
... )
558+
>>> session2.windows[0].name
559+
'editor'
539560
540-
>>> server.new_session(session_name='my session')
541-
Session($3 my session)
561+
>>> # Create session with environment variables
562+
>>> session3 = server.new_session(
563+
... session_name="env_test",
564+
... environment={"TEST_VAR": "test_value"}
565+
... )
566+
>>> session3.name
567+
'env_test'
568+
569+
>>> # Clean up
570+
>>> for name in ["basic", "custom", "env_test"]:
571+
... server.kill_session(name)
572+
Server(socket_path=/tmp/tmux-.../default)
573+
Server(socket_path=/tmp/tmux-.../default)
574+
Server(socket_path=/tmp/tmux-.../default)
542575
"""
543576
if session_name is not None:
544577
session_check_name(session_name)
@@ -598,11 +631,27 @@ def new_session(
598631

599632
@property
600633
def sessions(self) -> QueryList[Session]:
601-
"""Return a :class:`QueryList` of all :class:`Session` objects in this server.
634+
"""Return list of sessions.
602635
603-
Access advanced filtering and retrieval with:
604-
:meth:`.sessions.get() <libtmux._internal.query_list.QueryList.get()>` and
605-
:meth:`.sessions.filter() <libtmux._internal.query_list.QueryList.filter()>`
636+
Examples
637+
--------
638+
>>> server = Server()
639+
>>> # Clean up any existing test sessions first
640+
>>> for name in ["test1", "test2"]:
641+
... if server.has_session(name):
642+
... server.kill_session(name)
643+
>>> # Create some test sessions
644+
>>> session1 = server.new_session(session_name="test1")
645+
>>> session2 = server.new_session(session_name="test2")
646+
>>> len(server.sessions) >= 2 # May have other sessions
647+
True
648+
>>> sorted([s.name for s in server.sessions if s.name in ["test1", "test2"]])
649+
['test1', 'test2']
650+
>>> # Clean up
651+
>>> server.kill_session("test1")
652+
Server(socket_path=/tmp/tmux-.../default)
653+
>>> server.kill_session("test2")
654+
Server(socket_path=/tmp/tmux-.../default)
606655
"""
607656
sessions: list[Session] = []
608657
with contextlib.suppress(Exception):

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.