Skip to content

Commit 68982e9

Browse files
DenverCoder1DenverCoder1
authored
docs: Fix unlinked references and updated docstrings (#94)
1 parent c076989 commit 68982e9

File tree

6 files changed

+86
-39
lines changed

6 files changed

+86
-39
lines changed

‎docs/source/api.rst‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -39,31 +39,38 @@ TableStyle
3939
Exceptions
4040
~~~~~~~~~~
4141

42-
.. autoexception:: table2ascii.exceptions.Table2AsciiError
42+
.. autoexception:: Table2AsciiError
4343

44-
.. autoexception:: table2ascii.exceptions.TableOptionError
44+
.. autoexception:: TableOptionError
4545

46-
.. autoexception:: table2ascii.exceptions.ColumnCountMismatchError
46+
.. autoexception:: ColumnCountMismatchError
4747

48-
.. autoexception:: table2ascii.exceptions.FooterColumnCountMismatchError
48+
.. autoexception:: FooterColumnCountMismatchError
4949

50-
.. autoexception:: table2ascii.exceptions.BodyColumnCountMismatchError
50+
.. autoexception:: BodyColumnCountMismatchError
5151

52-
.. autoexception:: table2ascii.exceptions.AlignmentCountMismatchError
52+
.. autoexception:: AlignmentCountMismatchError
5353

54-
.. autoexception:: table2ascii.exceptions.InvalidCellPaddingError
54+
.. autoexception:: InvalidCellPaddingError
5555

56-
.. autoexception:: table2ascii.exceptions.ColumnWidthsCountMismatchError
56+
.. autoexception:: ColumnWidthsCountMismatchError
5757

58-
.. autoexception:: table2ascii.exceptions.ColumnWidthTooSmallError
58+
.. autoexception:: ColumnWidthTooSmallError
5959

60-
.. autoexception:: table2ascii.exceptions.InvalidColumnWidthError
60+
.. autoexception:: InvalidColumnWidthError
6161

62-
.. autoexception:: table2ascii.exceptions.InvalidAlignmentError
62+
.. autoexception:: InvalidAlignmentError
6363

64-
.. autoexception:: table2ascii.exceptions.TableStyleTooLongError
64+
.. autoexception:: TableStyleTooLongError
6565

6666
Warnings
6767
~~~~~~~~
6868

69-
.. autoclass:: table2ascii.exceptions.TableStyleTooShortWarning
69+
.. autoclass:: TableStyleTooShortWarning
70+
71+
Annotations
72+
~~~~~~~~~~~
73+
74+
.. autoclass:: SupportsStr
75+
76+
.. automethod:: SupportsStr.__str__

‎table2ascii/__init__.py‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,22 @@
55
from typing import TYPE_CHECKING
66

77
from .alignment import Alignment
8+
from .annotations import SupportsStr
9+
from .exceptions import (
10+
AlignmentCountMismatchError,
11+
BodyColumnCountMismatchError,
12+
ColumnCountMismatchError,
13+
ColumnWidthsCountMismatchError,
14+
ColumnWidthTooSmallError,
15+
FooterColumnCountMismatchError,
16+
InvalidAlignmentError,
17+
InvalidCellPaddingError,
18+
InvalidColumnWidthError,
19+
Table2AsciiError,
20+
TableOptionError,
21+
TableStyleTooLongError,
22+
TableStyleTooShortWarning,
23+
)
824
from .merge import Merge
925
from .preset_style import PresetStyle
1026
from .table_style import TableStyle
@@ -23,4 +39,18 @@
2339
"PresetStyle",
2440
"TableStyle",
2541
"table2ascii",
42+
"AlignmentCountMismatchError",
43+
"BodyColumnCountMismatchError",
44+
"ColumnCountMismatchError",
45+
"ColumnWidthsCountMismatchError",
46+
"ColumnWidthTooSmallError",
47+
"FooterColumnCountMismatchError",
48+
"InvalidAlignmentError",
49+
"InvalidCellPaddingError",
50+
"InvalidColumnWidthError",
51+
"Table2AsciiError",
52+
"TableOptionError",
53+
"TableStyleTooLongError",
54+
"TableStyleTooShortWarning",
55+
"SupportsStr",
2656
]

‎table2ascii/annotations.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@
1010

1111
@runtime_checkable
1212
class SupportsStr(Protocol):
13-
"""An ABC with one abstract method __str__."""
13+
"""An abstract base class (ABC) with one abstract method :meth:`__str__`"""
1414

1515
@abstractmethod
1616
def __str__(self) -> str:
17+
"""Return a string representation of the object"""
1718
pass

‎table2ascii/exceptions.py‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,9 @@ class FooterColumnCountMismatchError(ColumnCountMismatchError):
4040
This class is a subclass of :class:`ColumnCountMismatchError`.
4141
4242
Attributes:
43-
footer (Sequence[SupportsStr]): The footer that caused the error
44-
expected_columns (int): The number of columns that were expected
43+
footer (:class:`Sequence <collections.abc.Sequence>`\ [:class:`SupportsStr`]):
44+
The footer that caused the error
45+
expected_columns (:class:`int`): The number of columns that were expected
4546
"""
4647

4748
def __init__(self, footer: Sequence[SupportsStr], expected_columns: int):
@@ -63,9 +64,11 @@ class BodyColumnCountMismatchError(ColumnCountMismatchError):
6364
This class is a subclass of :class:`ColumnCountMismatchError`.
6465
6566
Attributes:
66-
body (Sequence[Sequence[SupportsStr]]): The body that caused the error
67-
expected_columns (int): The number of columns that were expected
68-
first_invalid_row (Sequence[SupportsStr]): The first row with an invalid column count
67+
body (:class:`Sequence <collections.abc.Sequence>`\ [\ :class:`Sequence <collections.abc.Sequence>`\ [:class:`SupportsStr`]]):
68+
The body that caused the error
69+
expected_columns (:class:`int`): The number of columns that were expected
70+
first_invalid_row (:class:`Sequence <collections.abc.Sequence>`\ [:class:`SupportsStr`]):
71+
The first row with an invalid column count
6972
"""
7073

7174
def __init__(self, body: Sequence[Sequence[SupportsStr]], expected_columns: int):
@@ -90,8 +93,9 @@ class AlignmentCountMismatchError(ColumnCountMismatchError):
9093
This class is a subclass of :class:`ColumnCountMismatchError`.
9194
9295
Attributes:
93-
alignments (Sequence[Alignment]): The alignments that caused the error
94-
expected_columns (int): The number of columns that were expected
96+
alignments (:class:`Sequence <collections.abc.Sequence>`\ [:class:`Alignment`]):
97+
The alignments that caused the error
98+
expected_columns (:class:`int`): The number of columns that were expected
9599
"""
96100

97101
def __init__(self, alignments: Sequence[Alignment], expected_columns: int):
@@ -113,8 +117,9 @@ class ColumnWidthsCountMismatchError(ColumnCountMismatchError):
113117
This class is a subclass of :class:`ColumnCountMismatchError`.
114118
115119
Attributes:
116-
column_widths (Sequence[Optional[int]]): The column widths that caused the error
117-
expected_columns (int): The number of columns that were expected
120+
column_widths (:class:`Sequence <collections.abc.Sequence>`\ [:data:`Optional <typing.Optional>`\ [:class:`int`]]):
121+
The column widths that caused the error
122+
expected_columns (:class:`int`): The number of columns that were expected
118123
"""
119124

120125
def __init__(self, column_widths: Sequence[int | None], expected_columns: int):
@@ -148,7 +153,7 @@ class InvalidCellPaddingError(TableOptionError):
148153
This class is a subclass of :class:`TableOptionError`.
149154
150155
Attributes:
151-
padding (int): The padding that caused the error
156+
padding (:class:`int`): The padding that caused the error
152157
"""
153158

154159
def __init__(self, padding: int):
@@ -169,9 +174,9 @@ class ColumnWidthTooSmallError(TableOptionError):
169174
This class is a subclass of :class:`TableOptionError`.
170175
171176
Attributes:
172-
column_index (int): The index of the column that caused the error
173-
column_width (int): The column width that caused the error
174-
min_width (int): The minimum width that is allowed
177+
column_index (:class:`int`): The index of the column that caused the error
178+
column_width (:class:`int`): The column width that caused the error
179+
min_width (:class:`int`): The minimum width that is allowed
175180
"""
176181

177182
def __init__(self, column_index: int, column_width: int, min_width: int | None = None):
@@ -208,7 +213,7 @@ class InvalidAlignmentError(TableOptionError):
208213
This class is a subclass of :class:`TableOptionError`.
209214
210215
Attributes:
211-
alignment (Any): The alignment value that caused the error
216+
alignment (:data:`Any <typing.Any>`): The alignment value that caused the error
212217
"""
213218

214219
def __init__(self, alignment: Any):
@@ -230,8 +235,8 @@ class TableStyleTooLongError(Table2AsciiError, ValueError):
230235
This class is a subclass of :class:`Table2AsciiError` and :class:`ValueError`.
231236
232237
Attributes:
233-
string (str): The string that caused the error
234-
max_characters (int): The maximum number of characters that are allowed
238+
string (:class:`str`): The string that caused the error
239+
max_characters (:class:`int`): The maximum number of characters that are allowed
235240
"""
236241

237242
def __init__(self, string: str, max_characters: int):
@@ -256,8 +261,8 @@ class TableStyleTooShortWarning(UserWarning):
256261
It can be silenced using :func:`warnings.filterwarnings`.
257262
258263
Attributes:
259-
string (str): The string that caused the warning
260-
max_characters (int): The number of characters that :class:`TableStyle` accepts
264+
string (:class:`str`): The string that caused the warning
265+
max_characters (:class:`int`): The number of characters that :class:`TableStyle` accepts
261266
"""
262267

263268
def __init__(self, string: str, max_characters: int):

‎table2ascii/table_style.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ def set(self, **kwargs: str) -> "TableStyle":
145145
146146
Example::
147147
148-
TableStyle().set(top_left_corner="╔", top_and_bottom_edge="═")
148+
TableStyle.from_string("~" * 30).set(left_and_right_edge="", col_sep="")
149149
"""
150150
for key, value in kwargs.items():
151151
setattr(self, key, value)

‎table2ascii/table_to_ascii.py‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -677,23 +677,27 @@ def table2ascii(
677677
"""Convert a 2D Python table to ASCII text
678678
679679
Args:
680-
header: List of column values in the table's header row. All values should be :class:`str`
680+
header (:data:`Optional <typing.Optional>`\ [:class:`Sequence <collections.abc.Sequence>`\ [:class:`SupportsStr`]]):
681+
List of column values in the table's header row. All values should be :class:`str`
681682
or support :class:`str` conversion. If not specified, the table will not have a header row.
682-
body: 2-dimensional list of values in the table's body. All values should be :class:`str`
683+
body (:data:`Optional <typing.Optional>`\ [:class:`Sequence <collections.abc.Sequence>`\ [:class:`Sequence <collections.abc.Sequence>`\ [:class:`SupportsStr`]]]):
684+
2-dimensional list of values in the table's body. All values should be :class:`str`
683685
or support :class:`str` conversion. If not specified, the table will not have a body.
684-
footer: List of column values in the table's footer row. All values should be :class:`str`
686+
footer (:data:`Optional <typing.Optional>`\ [:class:`Sequence <collections.abc.Sequence>`\ [:class:`SupportsStr`]]):
687+
List of column values in the table's footer row. All values should be :class:`str`
685688
or support :class:`str` conversion. If not specified, the table will not have a footer row.
686689
first_col_heading: Whether to add a header column separator after the first column.
687690
Defaults to :py:obj:`False`.
688691
last_col_heading: Whether to add a header column separator before the last column.
689692
Defaults to :py:obj:`False`.
690-
column_widths: List of widths in characters for each column. Any value of :py:obj:`None`
693+
column_widths (:data:`Optional <typing.Optional>`\ [:class:`Sequence <collections.abc.Sequence>`\ [:data:`Optional <typing.Optional>`\ [:class:`int`]]]):
694+
List of widths in characters for each column. Any value of :py:obj:`None`
691695
indicates that the column width should be determined automatically. If :py:obj:`None`
692696
is passed instead of a :class:`~collections.abc.Sequence`, all columns will be automatically
693697
sized. Defaults to :py:obj:`None`.
694698
alignments: List of alignments for each column
695-
(ex. ``[Alignment.LEFT, Alignment.CENTER, Alignment.RIGHT, Alignment.DECIMAL]``)
696-
or a single alignment to apply to all columns (ex. ``Alignment.LEFT``).
699+
(ex. [:attr:`Alignment.LEFT`, :attr:`Alignment.CENTER`, :attr:`Alignment.RIGHT`, :attr:`Alignment.DECIMAL`])
700+
or a single alignment to apply to all columns (ex. :attr:`Alignment.LEFT`).
697701
If not specified or set to :py:obj:`None`, all columns will be center-aligned.
698702
Defaults to :py:obj:`None`.
699703

0 commit comments

Comments
 (0)