Skip to content

reader ¤

Module to read a file/stream and pre-process the documentation lines.

Algorithm is as follows:

  1. preprocess_stream: yield documentation lines.
  2. preprocess_lines: group documentation lines as blocks of documentation.
  3. process_blocks: tidy blocks by tag in a dictionary.

Classes:

  • DocBlock –

    A documentation block.

  • DocFile –

    A shell script or documentation file.

  • DocLine –

    A documentation line.

  • DocStream –

    A stream of shell code or documentation.

  • DocType –

    Enumeration of the possible types of documentation.

DocBlock ¤

DocBlock(lines: list[DocLine] | None = None)

A documentation block.

Parameters:

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

    The block's doc lines.

Methods:

  • append –

    Append a line to the block.

Attributes:

Source code in src/shellman/reader.py 
86
87
88
89
90
91
92
93
94
def __init__(self, lines: list[DocLine] | None = None) -> None:
    """Initialize the doc block.

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

doc_type property ¤

doc_type: str

The block type.

first_line property ¤

first_line: DocLine

The block's first doc line.

lineno property ¤

lineno: int

The block's first line number.

lines_number property ¤

lines_number: int

The number of lines in the block.

path property ¤

path: str

The block's origin file path.

tag property ¤

tag: str

The block's tag.

value property ¤

value: str

The block's first line.

values property ¤

values: list[str]

The block's lines.

append ¤

append(line: DocLine) -> None

Append a line to the block.

Parameters:

  • line (DocLine) –

    The doc line to append.

Source code in src/shellman/reader.py 
102
103
104
105
106
107
108
def append(self, line: DocLine) -> None:
    """Append a line to the block.

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

DocFile ¤

DocFile(path: str)

A shell script or documentation file.

Parameters:

  • path (str) –

    The path to the file.

Source code in src/shellman/reader.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def __init__(self, path: str) -> None:
    """Initialize the documentation file.

    Parameters:
        path: The path to the file.
    """
    self.filepath = path
    self.filename = os.path.basename(path)
    with open(path, 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 = {}

DocLine ¤

DocLine(
    path: str, lineno: int, tag: str | None, value: str
)

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:

Source code in src/shellman/reader.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
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
    self.lineno = lineno
    self.tag = tag or ""
    self.value = value

doc_type property ¤

doc_type: str

The line's doc type.

DocStream ¤

DocStream(stream: Iterable[str], filename: str = '')

A stream of shell code or documentation.

Parameters:

  • stream (Iterable[str]) –

    A text stream.

  • filename (str, default: '' ) –

    An optional file name.

Source code in src/shellman/reader.py 
156
157
158
159
160
161
162
163
164
165
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
    self.filename = filename
    self.sections = _process_blocks(_preprocess_lines(_preprocess_stream(stream)))

DocType ¤

Enumeration of the possible types of documentation.

Attributes:

INVALID class-attribute instance-attribute ¤

INVALID = 'I'

Invalid type.

TAG class-attribute instance-attribute ¤

TAG = 'T'

A tag.

TAG_VALUE class-attribute instance-attribute ¤

TAG_VALUE = 'TV'

A tag its value.

VALUE class-attribute instance-attribute ¤

VALUE = 'V'

A value.