Skip to content

Commit 0fd574e

Browse files
tonytony
committed
docs(server): Add comprehensive docstrings for async methods
Enhance Server async method docstrings to first-class documentation standard: Server.ahas_session(): - Add detailed parameter descriptions with tmux version notes - Include 3 doctest examples (basic, concurrent, exact matching) - Add See Also section with cross-references - Document async usage patterns and benefits - Add version information (0.48.0) Server.anew_session(): - Expand all 9 parameter descriptions with detailed explanations - Add 6 comprehensive doctest examples covering: - Basic session creation - Custom working directory - Environment variables - Concurrent session creation - Custom window configuration - Document tmux command equivalents - Add warnings for command exit behavior - Include Notes section about async benefits - Add version information (0.48.0) Both docstrings now match the quality and depth of sync method documentation, following NumPy docstring conventions with: - Comprehensive parameter documentation - Multiple practical examples - Cross-references to related methods - Version annotations - tmux command equivalents - Async-specific usage notes
1 parent 0be56be commit 0fd574e

File tree

1 file changed

+223
-39
lines changed

1 file changed

+223
-39
lines changed

‎src/libtmux/server.py‎

Lines changed: 223 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -392,31 +392,90 @@ async def acmd(
392392
return await AsyncTmuxCmd.run(*svr_args, *cmd_args)
393393

394394
async def ahas_session(self, target_session: str, exact: bool = True) -> bool:
395-
"""Return True if session exists (async version).
395+
"""Return True if session exists asynchronously.
396+
397+
This is the async version of :meth:`has_session`. It uses ``await self.acmd()``
398+
for non-blocking session existence checks, making it suitable for async applications.
399+
400+
Equivalent to::
401+
402+
$ tmux has-session -t <target_session>
396403
397404
Parameters
398405
----------
399406
target_session : str
400-
session name
401-
exact : bool
402-
match the session name exactly. tmux uses fnmatch by default.
403-
Internally prepends ``=`` to the session in ``$ tmux has-session``.
404-
tmux 2.1 and up only.
407+
Session name to check for existence
408+
exact : bool, optional
409+
Match the session name exactly. When True (default), tmux will only
410+
match exact session names. When False, tmux uses fnmatch(3) pattern
411+
matching. Internally prepends ``=`` to the session when exact=True.
405412
406-
Raises
407-
------
408-
:exc:`exc.BadSessionName`
413+
.. note::
414+
415+
Exact matching requires tmux 2.1+. On older versions, this parameter
416+
is ignored and fnmatch behavior is used.
409417
410418
Returns
411419
-------
412420
bool
421+
True if session exists, False otherwise
422+
423+
Raises
424+
------
425+
:exc:`exc.BadSessionName`
426+
If target_session contains invalid characters (periods or colons)
427+
428+
See Also
429+
--------
430+
:meth:`has_session` : Synchronous version of this method
431+
:meth:`anew_session` : Create a new session asynchronously
432+
:meth:`kill_session` : Kill a session
433+
434+
Notes
435+
-----
436+
This method is non-blocking and suitable for use in async applications.
437+
It's particularly useful when checking multiple sessions concurrently using
438+
``asyncio.gather()``.
439+
440+
.. versionadded:: 0.48.0
441+
442+
Added async session existence check support.
413443
414444
Examples
415445
--------
416-
>>> await server.ahas_session("my_session")
446+
Basic session existence check:
447+
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")
417453
True
418454
>>> await server.ahas_session("nonexistent")
419455
False
456+
457+
Checking multiple sessions concurrently:
458+
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
470+
471+
Using exact matching:
472+
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
420479
"""
421480
session_check_name(target_session)
422481

@@ -443,73 +502,198 @@ async def anew_session(
443502
) -> Session:
444503
"""Create new session asynchronously, returns new :class:`Session`.
445504
446-
Uses ``-P`` flag to print session info, ``-F`` for return formatting
447-
returns new Session object.
505+
This is the async version of :meth:`new_session`. It uses ``await self.acmd()``
506+
for non-blocking session creation, making it suitable for async applications
507+
and enabling concurrent session creation.
448508
449-
``$ tmux new-session -d`` will create the session in the background
450-
``$ tmux new-session -Ad`` will move to the session name if it already
451-
exists. todo: make an option to handle this.
509+
Uses ``-P`` flag to print session info, ``-F`` for return formatting,
510+
and returns a new :class:`Session` object.
511+
512+
Equivalent to::
513+
514+
$ tmux new-session -d -s <session_name>
515+
516+
.. note::
517+
518+
``attach=False`` (default) creates the session in the background::
519+
520+
$ tmux new-session -d
521+
522+
This is typically desired for async operations to avoid blocking.
452523
453524
Parameters
454525
----------
455526
session_name : str, optional
456-
::
527+
Name for the new session. If not provided, tmux will auto-generate
528+
a name (typically sequential numbers: 0, 1, 2, etc.).
529+
530+
Equivalent to::
457531
458532
$ tmux new-session -s <session_name>
533+
459534
attach : bool, optional
460-
create session in the foreground. ``attach=False`` is equivalent
461-
to::
535+
Create session in the foreground (True) or background (False, default).
536+
For async operations, background creation is typically preferred.
537+
538+
``attach=False`` is equivalent to::
462539
463540
$ tmux new-session -d
464541
465542
Other Parameters
466543
----------------
467544
kill_session : bool, optional
468-
Kill current session if ``$ tmux has-session``.
469-
Useful for testing workspaces.
545+
If True, kill the existing session with the same name before creating
546+
a new one. If False (default) and a session with the same name exists,
547+
raises :exc:`exc.TmuxSessionExists`.
548+
549+
Useful for testing workspaces and ensuring a clean slate.
550+
470551
start_directory : str or PathLike, optional
471-
specifies the working directory in which the
472-
new session is created.
552+
Working directory in which the new session is created. All windows
553+
and panes in the session will default to this directory.
554+
555+
Supports pathlib.Path objects and tilde expansion (``~/``).
556+
557+
Equivalent to::
558+
559+
$ tmux new-session -c <start_directory>
560+
473561
window_name : str, optional
474-
::
562+
Name for the initial window created in the session.
563+
564+
Equivalent to::
475565
476566
$ tmux new-session -n <window_name>
567+
477568
window_command : str, optional
478-
execute a command on starting the session. The window will close
479-
when the command exits. NOTE: When this command exits the window
480-
will close. This feature is useful for long-running processes
481-
where the closing of the window upon completion is desired.
482-
x : [int, str], optional
483-
Force the specified width instead of the tmux default for a
484-
detached session
485-
y : [int, str], optional
486-
Force the specified height instead of the tmux default for a
487-
detached session
569+
Shell command to execute when starting the session. The window will
570+
automatically close when the command exits.
571+
572+
.. warning::
573+
574+
When this command exits, the window will close. This feature is
575+
useful for long-running processes where automatic cleanup is desired.
576+
577+
x : int or '-', optional
578+
Force the specified width (in columns) instead of the tmux default
579+
for a detached session. Use '-' for tmux default.
580+
581+
y : int or '-', optional
582+
Force the specified height (in rows) instead of the tmux default
583+
for a detached session. Use '-' for tmux default.
584+
585+
environment : dict[str, str], optional
586+
Dictionary of environment variables to set in the new session.
587+
Each key-value pair will be set as an environment variable.
588+
589+
.. note::
590+
591+
Requires tmux 3.2+. On older versions, this parameter is ignored
592+
with a warning.
593+
594+
Equivalent to::
595+
596+
$ tmux new-session -e KEY1=value1 -e KEY2=value2
488597
489598
Returns
490599
-------
491600
:class:`Session`
601+
The newly created session object
492602
493603
Raises
494604
------
495605
:exc:`exc.BadSessionName`
606+
If session_name contains invalid characters (periods or colons)
607+
:exc:`exc.TmuxSessionExists`
608+
If a session with the same name already exists and kill_session=False
609+
:exc:`exc.LibTmuxException`
610+
If tmux command execution fails
611+
612+
See Also
613+
--------
614+
:meth:`new_session` : Synchronous version of this method
615+
:meth:`ahas_session` : Check if a session exists asynchronously
616+
:meth:`kill_session` : Kill a session
617+
:class:`Session` : Session object documentation
618+
619+
Notes
620+
-----
621+
This method is non-blocking and suitable for use in async applications.
622+
It's particularly powerful when creating multiple sessions concurrently
623+
using ``asyncio.gather()``, which can significantly improve performance
624+
compared to sequential creation.
625+
626+
The method temporarily removes the ``TMUX`` environment variable during
627+
session creation to allow creating sessions from within tmux itself.
628+
629+
.. versionadded:: 0.48.0
630+
631+
Added async session creation support.
496632
497633
Examples
498634
--------
499-
Sessions can be created without a session name (0.14.2+):
635+
Sessions can be created without a session name (auto-generated IDs):
500636
501-
>>> await server.anew_session()
637+
>>> session = await server.anew_session()
638+
>>> session
502639
Session($2 2)
503640
504641
Creating them in succession will enumerate IDs (via tmux):
505642
506-
>>> await server.anew_session()
643+
>>> session2 = await server.anew_session()
644+
>>> session2
507645
Session($3 3)
508646
509-
With a `session_name`:
647+
With a custom `session_name`:
510648
511-
>>> await server.anew_session(session_name='my session')
512-
Session($4 my session)
649+
>>> session = await server.anew_session(session_name='my_project')
650+
>>> session
651+
Session($4 my_project)
652+
653+
With custom working directory:
654+
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)
662+
663+
With environment variables (tmux 3.2+):
664+
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)
674+
675+
Creating multiple sessions concurrently:
676+
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']
687+
688+
With custom window configuration:
689+
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'
513697
"""
514698
if session_name is not None:
515699
session_check_name(session_name)

0 commit comments

Comments
 (0)