shellman ¤

Bases: TextTag

A tag representing an author.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing a summary.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing a bug note.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing caveats.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing copyright information.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing a date.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing a description.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

A documentation block.

Parameters:

• lines ¤

  (list[DocLine] | None, default: None ) –

  The block's doc lines.

Methods:

• __bool__ –

  True if the block has lines.

• append –

  Append a line to the block.

Attributes:

• doc_type (str) –

  The block type.

• first_line (DocLine) –

  The block's first doc line.

• lineno (int) –

  The block's first line number.

• lines –

  The block's doc lines.

• lines_number (int) –

  The number of lines in the block.

• path (str) –

  The block's origin file path.

• tag (str) –

  The block's tag.

• value (str) –

  The block's first line.

• values (list[str]) –

  The block's lines.

113
114
115
116
117
118
119
120

def __init__(self, lines: list[DocLine] | None = None) -> None:
    """Initialize the doc block.

    Parameters:
        lines: The block's doc lines.
    """
    self.lines = lines if lines is not None else []
    """The block's doc lines."""

doc_type: str

first_line: DocLine

lineno: int

lines = lines if lines is not None else []

lines_number: int

path: str

tag: str

value: str

values: list[str]

__bool__() -> bool

122
123
124

def __bool__(self) -> bool:
    """True if the block has lines."""
    return bool(self.lines)

append(line: DocLine) -> None

129
130
131
132
133
134
135

def append(self, line: DocLine) -> None:
    """Append a line to the block.

    Parameters:
        line: The doc line to append.
    """
    self.lines.append(line)

A shell script or documentation file.

Parameters:

• path ¤

  (str) –

  The path to the file.

Attributes:

• filename –

  The file name.

• filepath –

  The file path.

• sections (dict[str, list[Tag]]) –

  The documentation sections.

201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

def __init__(self, path: str) -> None:
    """Initialize the documentation file.

    Parameters:
        path: The path to the file.
    """
    self.filepath = path
    """The file path."""
    self.filename = Path(path).name
    """The file name."""
    self.sections: dict[str, list[Tag]] = {}
    """The documentation sections."""

    with Path(path).open(encoding="utf-8") as stream:
        try:
            self.sections = _process_blocks(_preprocess_lines(_preprocess_stream(stream)))
        except UnicodeDecodeError:
            _logger.error(f"Cannot read file {path}")  # noqa: TRY400
            self.sections = {}

filename = Path(path).name

filepath = path

sections: dict[str, list[Tag]] = _process_blocks(
    _preprocess_lines(_preprocess_stream(stream))
)

A documentation line.

Parameters:

• path ¤

  (str) –

  The origin file path.

• lineno ¤

  (int) –

  The line number in the file.

• tag ¤

  (str | None) –

  The line's tag, if any.

• value ¤

  (str) –

  The line's value.

Attributes:

• doc_type (str) –

  The line's doc type.

• lineno –

  The line number in the file.

• path –

  The origin file path.

• tag –

  The line's tag.

• value –

  The line's value.

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

def __init__(self, path: str, lineno: int, tag: str | None, value: str) -> None:
    """Initialize the doc line.

    Parameters:
        path: The origin file path.
        lineno: The line number in the file.
        tag: The line's tag, if any.
        value: The line's value.
    """
    self.path = path
    """The origin file path."""
    self.lineno = lineno
    """The line number in the file."""
    self.tag = tag or ""
    """The line's tag."""
    self.value = value
    """The line's value."""

doc_type: str

lineno = lineno

path = path

tag = tag or ''

value = value

A stream of shell code or documentation.

Parameters:

• stream ¤

  (Iterable[str]) –

  A text stream.

• filename ¤

  (str, default: '' ) –

  An optional file name.

Attributes:

• filename –

  The file name.

• filepath –

  The file path.

• sections –

  The documentation sections.

183
184
185
186
187
188
189
190
191
192
193
194
195

def __init__(self, stream: Iterable[str], filename: str = "") -> None:
    """Initialize the documentation file.

    Parameters:
        stream: A text stream.
        filename: An optional file name.
    """
    self.filepath = None
    """The file path."""
    self.filename = filename
    """The file name."""
    self.sections = _process_blocks(_preprocess_lines(_preprocess_stream(stream)))
    """The documentation sections."""

filename = filename

filepath = None

sections = _process_blocks(
    _preprocess_lines(_preprocess_stream(stream))
)

Enumeration of the possible types of documentation.

Attributes:

• INVALID –

  Invalid type.

• TAG –

  A tag.

• TAG_VALUE –

  A tag its value.

• VALUE –

  A value.

INVALID = 'I'

TAG = 'T'

TAG_VALUE = 'TV'

VALUE = 'V'

Bases: ValueDescTag

A tag representing an environment variable used by the script.

Methods:

• from_lines –

  Parse a value and its description from documentation lines.

Attributes:

• description (str) –

  The environment variable description.

• description_field_name (str) –

  The name of the field containing the description.

• name (str) –

  The environment variable name.

• tag (str) –

  The tag name used to identify environment variables.

• value_field_name (str) –

  The name of the field containing the value.

description: str

description_field_name: str = 'description'

name: str

tag: str = 'env'

value_field_name: str = 'name'

from_lines(lines: Sequence[DocLine]) -> Self

 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> Self:
    """Parse a value and its description from documentation lines.

    Parameters:
        lines: The documentation lines containing the value and description.

    Returns:
        A tag instance with the value and description stored in the configured fields.
    """
    value, description = "", []
    for line in lines:
        if line.tag == cls.tag:
            split = line.value.split(" ", 1)
            if len(split) > 1:
                value = split[0]
                description.append(split[1])
            else:
                value = split[0]
        else:
            description.append(line.value)
    return cls(**{cls.value_field_name: value, cls.description_field_name: "\n".join(description)})

Bases: TextTag

A tag representing a known error.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: Tag

A tag representing a code/shell example.

Methods:

• from_lines –

  Parse an example's summary, code, language, and description.

Attributes:

• brief (str) –

  The example's summary.

• code (str) –

  The example's code.

• code_lang (str) –

  The example's language.

• description (str) –

  The example's description.

brief: str

code: str

code_lang: str

description: str

from_lines(lines: Sequence[DocLine]) -> ExampleTag

182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> ExampleTag:
    """Parse an example's summary, code, language, and description.

    Parameters:
        lines: The documentation lines containing the example and its sections.

    Returns:
        An example tag with the parsed sections.
    """
    brief, code, description = [], [], []
    code_lang = ""
    current = None
    for line in lines:
        if line.tag == "example":
            if line.value:
                brief.append(line.value)
            current = "brief"
        elif line.tag == "example-code":
            if line.value:
                code_lang = line.value
            current = "code"
        elif line.tag == "example-description":
            if line.value:
                description.append(line.value)
            current = "description"
        elif current == "brief":
            brief.append(line.value)
        elif current == "code":
            code.append(line.value)
        elif current == "description":
            description.append(line.value)

    return ExampleTag(
        brief="\n".join(brief),
        code="\n".join(code),
        code_lang=code_lang,
        description="\n".join(description),
    )

Bases: ValueDescTag

A tag representing an exit code.

Methods:

• from_lines –

  Parse a value and its description from documentation lines.

Attributes:

• code (str) –

  The exit code value.

• description (str) –

  The exit code description.

• description_field_name (str) –

  The name of the field containing the description.

• tag (str) –

  The tag name used to identify exit codes.

• value_field_name (str) –

  The name of the field containing the exit code.

code: str

description: str

description_field_name: str = 'description'

tag: str = 'exit'

value_field_name: str = 'code'

from_lines(lines: Sequence[DocLine]) -> Self

 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> Self:
    """Parse a value and its description from documentation lines.

    Parameters:
        lines: The documentation lines containing the value and description.

    Returns:
        A tag instance with the value and description stored in the configured fields.
    """
    value, description = "", []
    for line in lines:
        if line.tag == cls.tag:
            split = line.value.split(" ", 1)
            if len(split) > 1:
                value = split[0]
                description.append(split[1])
            else:
                value = split[0]
        else:
            description.append(line.value)
    return cls(**{cls.value_field_name: value, cls.description_field_name: "\n".join(description)})

Bases: ValueDescTag

A tag representing a file used by a script.

Methods:

• from_lines –

  Parse a value and its description from documentation lines.

Attributes:

• description (str) –

  The file description.

• description_field_name (str) –

  The name of the field containing the description.

• name (str) –

  The file name/path.

• tag (str) –

  The tag name used to identify files.

• value_field_name (str) –

  The name of the field containing the value.

description: str

description_field_name: str = 'description'

name: str

tag: str = 'file'

value_field_name: str = 'name'

from_lines(lines: Sequence[DocLine]) -> Self

 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> Self:
    """Parse a value and its description from documentation lines.

    Parameters:
        lines: The documentation lines containing the value and description.

    Returns:
        A tag instance with the value and description stored in the configured fields.
    """
    value, description = "", []
    for line in lines:
        if line.tag == cls.tag:
            split = line.value.split(" ", 1)
            if len(split) > 1:
                value = split[0]
                description.append(split[1])
            else:
                value = split[0]
        else:
            description.append(line.value)
    return cls(**{cls.value_field_name: value, cls.description_field_name: "\n".join(description)})

Bases: Tag

A tag representing a shell function.

Methods:

• from_lines –

  Parse a shell function's prototype and documentation sections.

Attributes:

• arguments (Sequence[str]) –

  The function's arguments.

• brief (str) –

  The function's summary.

• description (str) –

  The function's description.

• preconditions (Sequence[str]) –

  The function's preconditions.

• prototype (str) –

  The function's prototype.

• return_codes (Sequence[str]) –

  The function's return codes.

• seealso (Sequence[str]) –

  The function's "see also" information.

• stderr (Sequence[str]) –

  The function's standard error.

• stdin (Sequence[str]) –

  The function's standard input.

• stdout (Sequence[str]) –

  The function's standard output.

arguments: Sequence[str]

brief: str

description: str

preconditions: Sequence[str]

prototype: str

return_codes: Sequence[str]

seealso: Sequence[str]

stderr: Sequence[str]

stdin: Sequence[str]

stdout: Sequence[str]

from_lines(lines: Sequence[DocLine]) -> FunctionTag

276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> FunctionTag:
    """Parse a shell function's prototype and documentation sections.

    Parameters:
        lines: The documentation lines containing the function and its sections.

    Returns:
        A function tag with the parsed prototype and documentation.
    """
    brief = ""
    prototype = ""
    description = []
    arguments = []
    return_codes = []
    preconditions = []
    seealso = []
    stderr = []
    stdin = []
    stdout = []
    for line in lines:
        if line.tag == "function":
            prototype = line.value
        elif line.tag == "function-brief":
            brief = line.value
        elif line.tag == "function-description":
            description.append(line.value)
        elif line.tag == "function-argument":
            arguments.append(line.value)
        elif line.tag == "function-precondition":
            preconditions.append(line.value)
        elif line.tag == "function-return":
            return_codes.append(line.value)
        elif line.tag == "function-seealso":
            seealso.append(line.value)
        elif line.tag == "function-stderr":
            stderr.append(line.value)
        elif line.tag == "function-stdin":
            stdin.append(line.value)
        elif line.tag == "function-stdout":
            stdout.append(line.value)
        else:
            description.append(line.value)

    return FunctionTag(
        prototype=prototype,
        brief=brief,
        description="\n".join(description),
        arguments=arguments,
        preconditions=preconditions,
        return_codes=return_codes,
        seealso=seealso,
        stderr=stderr,
        stdin=stdin,
        stdout=stdout,
    )

Bases: TextTag

A tag representing a script's history.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing a license.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing a note.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: Tag

A tag representing a command-line option.

Methods:

• from_lines –

  Parse an option's flags, arguments, default value, group, and description.

Attributes:

• default (str) –

  The option default value.

• description (str) –

  The option description.

• group (str) –

  The option group.

• long (str) –

  The option long flag.

• positional (str) –

  The option positional arguments.

• short (str) –

  The option short flag.

• signature (str) –

  The signature of the option.

default: str

description: str

group: str

long: str

positional: str

short: str

signature: str

from_lines(lines: Sequence[DocLine]) -> OptionTag

384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> OptionTag:
    """Parse an option's flags, arguments, default value, group, and description.

    Parameters:
        lines: The documentation lines containing the option and its sections.

    Returns:
        An option tag with the parsed signature and supporting information.
    """
    short, long, positional, default, group = "", "", "", "", ""
    description = []
    for line in lines:
        if line.tag == "option":
            search = re.search(
                r"^(?P<short>-\w)?(?:, )?(?P<long>--[\w-]+)? ?(?P<positional>.+)?",
                line.value,
            )
            if search:
                short, long, positional = search.groups(default="")
            else:
                positional = line.value
        elif line.tag == "option-default":
            default = line.value
        elif line.tag == "option-group":
            group = line.value
        else:
            description.append(line.value)
    return OptionTag(
        short=short,
        long=long,
        positional=positional,
        default=default,
        group=group,
        description="\n".join(description),
    )

Bases: TextTag

A tag representing "See Also" information.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str

from_lines(lines: Sequence[DocLine]) -> TextTag

66
67
68
69
70
71
72
73
74
75
76

@classmethod
def from_lines(cls, lines: Sequence[DocLine]) -> TextTag:
    """Join documentation line values into a text tag.

    Parameters:
        lines: The documentation lines to parse.

    Returns:
        A tag instance with line values joined by newline characters.
    """
    return cls(text="\n".join(line.value for line in lines))

Bases: TextTag

A tag representing the standard error of a script/function.

Methods:

• from_lines –

  Join documentation line values into a text tag.

Attributes:

• text (str) –

  The tag's text.

text: str