Skip to content

Commit 5f3c870

Browse files
tonytony
committed
docs(server): Convert async examples to narrative code blocks
Fix async docstring examples to use narrative code blocks (::) instead of executable doctests (>>>). This is necessary because: 1. Standard Python doctests don't support top-level await statements 2. pytest-asyncio doesn't integrate with doctest by default 3. Narrative examples are clearer for async patterns Changes: - Server.ahas_session(): Convert 3 examples to narrative style - Server.anew_session(): Convert 6 examples to narrative style Examples now show realistic async/await code with inline comments explaining the results, making them more readable and maintainable while avoiding doctest execution issues. This matches Python's asyncio documentation pattern where async examples are shown as code blocks rather than interactive sessions. All existing sync doctests continue to pass (8/8 passing).
1 parent 0fd574e commit 5f3c870

File tree

1 file changed

+73
-77
lines changed

1 file changed

+73
-77
lines changed

‎src/libtmux/server.py‎

Lines changed: 73 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -443,39 +443,42 @@ async def ahas_session(self, target_session: str, exact: bool = True) -> bool:
443443
444444
Examples
445445
--------
446-
Basic session existence check:
446+
Basic session existence check::
447447
448-
>>> async def check_session_exists():
449-
... exists = await server.ahas_session("my_session")
450-
... return exists
451-
>>> session = await server.anew_session("test_exists")
452-
>>> await server.ahas_session("test_exists")
453-
True
454-
>>> await server.ahas_session("nonexistent")
455-
False
448+
async def check_session_exists():
449+
session = await server.anew_session("test_exists")
450+
exists = await server.ahas_session("test_exists")
451+
return exists
456452
457-
Checking multiple sessions concurrently:
453+
Checking multiple sessions concurrently::
458454
459-
>>> async def check_multiple_sessions():
460-
... results = await asyncio.gather(
461-
... server.ahas_session("session_1"),
462-
... server.ahas_session("session_2"),
463-
... server.ahas_session("session_3"),
464-
... )
465-
... return results
466-
>>> await server.anew_session("concurrent_test")
467-
Session(...)
468-
>>> await server.ahas_session("concurrent_test")
469-
True
455+
async def check_multiple_sessions():
456+
# Create sessions concurrently
457+
await asyncio.gather(
458+
server.anew_session("session_1"),
459+
server.anew_session("session_2"),
460+
server.anew_session("session_3"),
461+
)
470462
471-
Using exact matching:
463+
# Check all sessions concurrently
464+
results = await asyncio.gather(
465+
server.ahas_session("session_1"),
466+
server.ahas_session("session_2"),
467+
server.ahas_session("session_3"),
468+
)
469+
# results will be [True, True, True]
470+
return results
472471
473-
>>> await server.anew_session("exact_match_test")
474-
Session(...)
475-
>>> await server.ahas_session("exact_match_test", exact=True)
476-
True
477-
>>> await server.ahas_session("exact", exact=True) # Partial name, exact match
478-
False
472+
Using exact matching::
473+
474+
session = await server.anew_session("exact_match_test")
475+
476+
# Exact match - must match full name
477+
await server.ahas_session("exact_match_test", exact=True) # True
478+
await server.ahas_session("exact", exact=True) # False - partial name
479+
480+
# Fuzzy match (exact=False) uses fnmatch
481+
await server.ahas_session("exact*", exact=False) # True
479482
"""
480483
session_check_name(target_session)
481484

@@ -632,68 +635,61 @@ async def anew_session(
632635
633636
Examples
634637
--------
635-
Sessions can be created without a session name (auto-generated IDs):
638+
Sessions can be created without a session name (auto-generated IDs)::
636639
637-
>>> session = await server.anew_session()
638-
>>> session
639-
Session($2 2)
640+
session = await server.anew_session()
641+
# Session($2 2) - auto-generated name
640642
641-
Creating them in succession will enumerate IDs (via tmux):
643+
session2 = await server.anew_session()
644+
# Session($3 3) - sequential IDs
642645
643-
>>> session2 = await server.anew_session()
644-
>>> session2
645-
Session($3 3)
646+
With a custom `session_name`::
646647
647-
With a custom `session_name`:
648+
session = await server.anew_session(session_name='my_project')
649+
# Session($4 my_project)
648650
649-
>>> session = await server.anew_session(session_name='my_project')
650-
>>> session
651-
Session($4 my_project)
651+
With custom working directory::
652652
653-
With custom working directory:
653+
from pathlib import Path
654654
655-
>>> from pathlib import Path
656-
>>> session = await server.anew_session(
657-
... session_name='dev_session',
658-
... start_directory='/tmp'
659-
... )
660-
>>> session
661-
Session($5 dev_session)
655+
session = await server.anew_session(
656+
session_name='dev_session',
657+
start_directory='/tmp'
658+
)
659+
# All windows/panes will default to /tmp
662660
663-
With environment variables (tmux 3.2+):
661+
With environment variables (tmux 3.2+)::
664662
665-
>>> session = await server.anew_session(
666-
... session_name='env_session',
667-
... environment={
668-
... 'PROJECT_ENV': 'development',
669-
... 'DEBUG': 'true'
670-
... }
671-
... )
672-
>>> session
673-
Session($6 env_session)
663+
session = await server.anew_session(
664+
session_name='env_session',
665+
environment={
666+
'PROJECT_ENV': 'development',
667+
'DEBUG': 'true'
668+
}
669+
)
670+
# Environment variables available in session
674671
675-
Creating multiple sessions concurrently:
672+
Creating multiple sessions concurrently::
676673
677-
>>> import asyncio
678-
>>> sessions = await asyncio.gather(
679-
... server.anew_session(session_name='frontend'),
680-
... server.anew_session(session_name='backend'),
681-
... server.anew_session(session_name='database'),
682-
... )
683-
>>> len(sessions)
684-
3
685-
>>> [s.session_name for s in sessions]
686-
['frontend', 'backend', 'database']
674+
import asyncio
675+
676+
sessions = await asyncio.gather(
677+
server.anew_session(session_name='frontend'),
678+
server.anew_session(session_name='backend'),
679+
server.anew_session(session_name='database'),
680+
)
681+
# All three sessions created in parallel
682+
# len(sessions) == 3
683+
# [s.session_name for s in sessions] == ['frontend', 'backend', 'database']
687684
688-
With custom window configuration:
685+
With custom window configuration::
689686
690-
>>> session = await server.anew_session(
691-
... session_name='custom_window',
692-
... window_name='main',
693-
... window_command='htop'
694-
... )
695-
>>> session.active_window.window_name
696-
'main'
687+
session = await server.anew_session(
688+
session_name='custom_window',
689+
window_name='main',
690+
window_command='htop'
691+
)
692+
# session.active_window.window_name == 'main'
697693
"""
698694
if session_name is not None:
699695
session_check_name(session_name)

0 commit comments

Comments
 (0)