sveden-table-matrixizer 1.0.0__tar.gz

sveden_table_matrixizer-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gorshipisk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sveden_table_matrixizer-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: sveden-table-matrixizer
+Version: 1.0.0
+Summary: Module for convert tables from HTML-pages (/sveden) to matrix of bs4 tags
+Author: BestTvGU
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4==4.14.3
+Requires-Dist: aiohttp==3.13.5
+Dynamic: license-file
+
+# sveden-table-matrixizer
+
+**Extract and matrixize HTML tables from Russian educational organization pages (`/sveden`) with full colspan/rowspan
+support.**
+
+`sveden-table-matrixizer` is an asynchronous Python library that parses tables found on `/sveden` (сведения об
+образовательной организации) pages, expands `colspan` and `rowspan` attributes into clean two-dimensional matrices, and
+returns structured `head` and `body` cell grids. It gives you full control over edge cases via configurable callbacks.
+
+## Features
+
+- **Async page fetching** using `aiohttp`.
+- **Full colspan/rowspan expansion** – cells spanning multiple rows and/or columns are duplicated into the matrix.
+- **Separate head and body matrix extraction** – each table yields a `head` matrix (from `<thead>`) and a `body`
+  matrix (from `<tbody>`).
+- **Customizable error handling** – replace default reactions to missing headers, missing bodies, or multiple `<thead>`/
+  `<tbody>` elements.
+- **Lightweight** – only depends on `aiohttp` and `beautifulsoup4`.
+- **Works with any HTML** – designed for `/sveden`, but usable on any page containing `<table>` elements.
+
+## Installation
+
+```bash
+pip install sveden-table-matrixizer
+```
+
+## Quick Start
+
+```python
+import asyncio
+from sveden_table_matrixizer import matrixize_tables_from_page
+
+
+async def main():
+    url = "https://example.edu/sveden/"
+    tables = await matrixize_tables_from_page(url)
+
+    for i, table in enumerate(tables):
+        print(f"Table {i + 1}:")
+        print("  Head rows:", len(table.head))
+        print("  Body rows:", len(table.body))
+        # Access cells as list[list[bs4.Tag]]
+
+
+asyncio.run(main())
+```
+
+Each `MatrixizedTable` contains:
+
+- `head: list[list[Tag]]` – rows of header cells _(each row is a list of `bs4.Tag`)_.
+- `body: list[list[Tag]]` – rows of body cells.
+
+## Handling Edge Cases
+
+By default, the extractor raises exceptions when a table lacks a header or body, or contains more than one `<thead>` /
+`<tbody>`. You can override this behavior with `ExtractorOptions`.
+
+```python
+from sveden_table_matrixizer import matrixize_tables_from_page, ExtractorOptions
+from sveden_table_matrixizer.def_funcs import MatrixizedTable
+
+
+def handle_missing_header(table_tag, collected_tables):
+    print(f"Skipping table without <thead>: {table_tag.get('id', 'no id')}")
+
+
+opts = ExtractorOptions(
+    on_table_no_header=handle_missing_header,
+    # other callbacks can be set similarly
+)
+
+tables = await matrixize_tables_from_page(url, options=opts)
+```
+
+You can also supply async callbacks – the library automatically detects and awaits them.
+
+## API Reference
+
+### `matrixize_tables_from_page(url, *, options=None)`
+
+- **Parameters:**
+    - `url` (`str`) – URL of the page to scrape.
+    - `options` (`ExtractorOptions`, optional) – configuration callbacks.
+- **Returns:** `list[MatrixizedTable]` – extracted and matrixized tables.
+
+### `ExtractorOptions`
+
+A frozen dataclass with the following fields (all optional):
+
+| Field                       | Type                                              | Default                           | Description                                                                           |
+|-----------------------------|---------------------------------------------------|-----------------------------------|---------------------------------------------------------------------------------------|
+| `on_table_no_header`        | `Callable[[Tag, Sequence[MatrixizedTable]], Any]` | no‑op                             | Called when a table has no `<thead>`                                                  |
+| `on_table_no_body`          | `Callable[[Tag, Sequence[MatrixizedTable]], Any]` | no‑op                             | Called when a table has no `<tbody>`                                                  |
+| `on_multiply_table_headers` | `Callable[[Sequence[Tag]], Tag \| Never]`         | raises `MultiplyTableHeaderError` | Called when more than one `<thead>` is found; must return a single `<thead>` element. |
+| `on_multiply_table_bodies`  | `Callable[[Sequence[Tag]], Tag \| Never]`         | raises `MultiplyTableBodyError`   | Called when more than one `<tbody>` is found; must return a single `<tbody>` element. |
+
+### `MatrixizedTable`
+
+```python
+@dataclass(frozen=True, kw_only=True)
+class MatrixizedTable:
+    head: list[list[Tag]]  # matrix of <th> tags
+    body: list[list[Tag]]  # matrix of <td> tags
+```
+
+### Exceptions
+
+- `NoTableHeaderError` – raised when `options.on_table_no_header` is not overridden.
+- `NoTableBodyError` – raised when `options.on_table_no_body` is not overridden.
+- `MultiplyTableHeaderError` – default reaction to multiple `<thead>` elements.
+- `MultiplyTableBodyError` – default reaction to multiple `<tbody>` elements.
+
+All exceptions are exported from `sveden_table_matrixizer.errors`.
+
+## How It Works
+
+1. The page is fetched with `aiohttp` and parsed by BeautifulSoup.
+2. All `<table>` tags are collected.
+3. For each table:
+    - The `<thead>` is located; if missing or duplicate, the appropriate callback is invoked.
+    - The `<tbody>` is located similarly.
+    - Header rows are expanded: each `<th>` with `colspan`/`rowspan` is replicated into the correct cells of a 2D list.
+    - The same expansion is applied to body rows using `<td>` elements.
+4. A `MatrixizedTable(head=..., body=...)` is created and added to the result list.
+
+## Dependencies
+
+- Python ≥ 3.11
+- [aiohttp](https://pypi.org/project/aiohttp/)
+- [beautifulsoup4](https://pypi.org/project/beautifulsoup4/)
+
+## License
+
+This project is licensed under the MIT License – see the source repository for details.

sveden_table_matrixizer-1.0.0/README.md

@@ -0,0 +1,134 @@
+# sveden-table-matrixizer
+
+**Extract and matrixize HTML tables from Russian educational organization pages (`/sveden`) with full colspan/rowspan
+support.**
+
+`sveden-table-matrixizer` is an asynchronous Python library that parses tables found on `/sveden` (сведения об
+образовательной организации) pages, expands `colspan` and `rowspan` attributes into clean two-dimensional matrices, and
+returns structured `head` and `body` cell grids. It gives you full control over edge cases via configurable callbacks.
+
+## Features
+
+- **Async page fetching** using `aiohttp`.
+- **Full colspan/rowspan expansion** – cells spanning multiple rows and/or columns are duplicated into the matrix.
+- **Separate head and body matrix extraction** – each table yields a `head` matrix (from `<thead>`) and a `body`
+  matrix (from `<tbody>`).
+- **Customizable error handling** – replace default reactions to missing headers, missing bodies, or multiple `<thead>`/
+  `<tbody>` elements.
+- **Lightweight** – only depends on `aiohttp` and `beautifulsoup4`.
+- **Works with any HTML** – designed for `/sveden`, but usable on any page containing `<table>` elements.
+
+## Installation
+
+```bash
+pip install sveden-table-matrixizer
+```
+
+## Quick Start
+
+```python
+import asyncio
+from sveden_table_matrixizer import matrixize_tables_from_page
+
+
+async def main():
+    url = "https://example.edu/sveden/"
+    tables = await matrixize_tables_from_page(url)
+
+    for i, table in enumerate(tables):
+        print(f"Table {i + 1}:")
+        print("  Head rows:", len(table.head))
+        print("  Body rows:", len(table.body))
+        # Access cells as list[list[bs4.Tag]]
+
+
+asyncio.run(main())
+```
+
+Each `MatrixizedTable` contains:
+
+- `head: list[list[Tag]]` – rows of header cells _(each row is a list of `bs4.Tag`)_.
+- `body: list[list[Tag]]` – rows of body cells.
+
+## Handling Edge Cases
+
+By default, the extractor raises exceptions when a table lacks a header or body, or contains more than one `<thead>` /
+`<tbody>`. You can override this behavior with `ExtractorOptions`.
+
+```python
+from sveden_table_matrixizer import matrixize_tables_from_page, ExtractorOptions
+from sveden_table_matrixizer.def_funcs import MatrixizedTable
+
+
+def handle_missing_header(table_tag, collected_tables):
+    print(f"Skipping table without <thead>: {table_tag.get('id', 'no id')}")
+
+
+opts = ExtractorOptions(
+    on_table_no_header=handle_missing_header,
+    # other callbacks can be set similarly
+)
+
+tables = await matrixize_tables_from_page(url, options=opts)
+```
+
+You can also supply async callbacks – the library automatically detects and awaits them.
+
+## API Reference
+
+### `matrixize_tables_from_page(url, *, options=None)`
+
+- **Parameters:**
+    - `url` (`str`) – URL of the page to scrape.
+    - `options` (`ExtractorOptions`, optional) – configuration callbacks.
+- **Returns:** `list[MatrixizedTable]` – extracted and matrixized tables.
+
+### `ExtractorOptions`
+
+A frozen dataclass with the following fields (all optional):
+
+| Field                       | Type                                              | Default                           | Description                                                                           |
+|-----------------------------|---------------------------------------------------|-----------------------------------|---------------------------------------------------------------------------------------|
+| `on_table_no_header`        | `Callable[[Tag, Sequence[MatrixizedTable]], Any]` | no‑op                             | Called when a table has no `<thead>`                                                  |
+| `on_table_no_body`          | `Callable[[Tag, Sequence[MatrixizedTable]], Any]` | no‑op                             | Called when a table has no `<tbody>`                                                  |
+| `on_multiply_table_headers` | `Callable[[Sequence[Tag]], Tag \| Never]`         | raises `MultiplyTableHeaderError` | Called when more than one `<thead>` is found; must return a single `<thead>` element. |
+| `on_multiply_table_bodies`  | `Callable[[Sequence[Tag]], Tag \| Never]`         | raises `MultiplyTableBodyError`   | Called when more than one `<tbody>` is found; must return a single `<tbody>` element. |
+
+### `MatrixizedTable`
+
+```python
+@dataclass(frozen=True, kw_only=True)
+class MatrixizedTable:
+    head: list[list[Tag]]  # matrix of <th> tags
+    body: list[list[Tag]]  # matrix of <td> tags
+```
+
+### Exceptions
+
+- `NoTableHeaderError` – raised when `options.on_table_no_header` is not overridden.
+- `NoTableBodyError` – raised when `options.on_table_no_body` is not overridden.
+- `MultiplyTableHeaderError` – default reaction to multiple `<thead>` elements.
+- `MultiplyTableBodyError` – default reaction to multiple `<tbody>` elements.
+
+All exceptions are exported from `sveden_table_matrixizer.errors`.
+
+## How It Works
+
+1. The page is fetched with `aiohttp` and parsed by BeautifulSoup.
+2. All `<table>` tags are collected.
+3. For each table:
+    - The `<thead>` is located; if missing or duplicate, the appropriate callback is invoked.
+    - The `<tbody>` is located similarly.
+    - Header rows are expanded: each `<th>` with `colspan`/`rowspan` is replicated into the correct cells of a 2D list.
+    - The same expansion is applied to body rows using `<td>` elements.
+4. A `MatrixizedTable(head=..., body=...)` is created and added to the result list.
+
+## Dependencies
+
+- Python ≥ 3.11
+- [aiohttp](https://pypi.org/project/aiohttp/)
+- [beautifulsoup4](https://pypi.org/project/beautifulsoup4/)
+
+## License
+
+This project is licensed under the MIT License – see the source repository for details.

sveden_table_matrixizer-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sveden-table-matrixizer"
+version = "1.0.0"
+description = "Module for convert tables from HTML-pages (/sveden) to matrix of bs4 tags"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+
+authors = [
+    { name = "BestTvGU" }
+]
+
+dependencies = [
+    "beautifulsoup4==4.14.3",
+    "aiohttp==3.13.5"
+]
+
+[tool.setuptools]
+packages = ["sveden_table_matrixizer"]
+
+[tool.setuptools.package-data]
+besttvgu_backend = ["py.typed"]

sveden_table_matrixizer-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/__init__.py

@@ -0,0 +1,3 @@
+from .tables_extractor import matrixize_tables_from_page
+
+__all__ = ["matrixize_tables_from_page"]

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/def_funcs.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+from typing import Never
+
+from bs4 import Tag, ResultSet
+
+from .errors import MultiplyTableHeaderError, MultiplyTableBodyError
+
+
+@dataclass(frozen=True, kw_only=True)
+class MatrixizedTable:
+    head: list[list[Tag]]
+    body: list[list[Tag]]
+
+
+def on_table_no_header_def(_table: Tag, _matrixized_tables: list[MatrixizedTable]) -> None:
+    pass
+
+
+def on_table_no_body_def(_table: Tag, _matrixized_tables: list[MatrixizedTable]) -> None:
+    pass
+
+
+def on_multiply_table_headers_def(_heads: ResultSet[Tag]) -> Never:
+    raise MultiplyTableHeaderError
+
+
+def on_multiply_table_bodies_def(_bodies: ResultSet[Tag]) -> Never:
+    raise MultiplyTableBodyError

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/errors.py

@@ -0,0 +1,14 @@
+class NoTableHeaderError(Exception):
+    pass
+
+
+class MultiplyTableHeaderError(Exception):
+    pass
+
+
+class NoTableBodyError(Exception):
+    pass
+
+
+class MultiplyTableBodyError(Exception):
+    pass

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/table_body_extractor.py

@@ -0,0 +1,50 @@
+from typing import Generator
+
+from bs4 import Tag, ResultSet
+
+from .errors import NoTableBodyError
+from .types import ExtractorOptions
+from .utils import handle_maybe_async
+
+
+async def extract_table_body(table: Tag, *, options: ExtractorOptions) -> Tag:
+    bodies: ResultSet[Tag] = table.find_all("tbody", recursive=False)
+
+    if len(bodies) == 0:
+        raise NoTableBodyError
+    if len(bodies) > 1:
+        return await handle_maybe_async(options.on_multiply_table_bodies, bodies)
+
+    return bodies[0]
+
+
+def body_tr_generator(tr_tag: Tag) -> Generator[tuple[Tag, int, int], None, None]:
+    for td_tag in tr_tag.find_all("td", recursive=False):
+        td_colspan: int = int(td_tag.get("colspan") or 1)
+        td_rowspan: int = int(td_tag.get("rowspan") or 1)
+
+        yield td_tag, td_colspan, td_rowspan
+
+
+def body_table_generator(table_body: Tag) -> Generator[Generator[tuple[Tag, int, int], None, None], None, None]:
+    for tr_tag in table_body.find_all("tr", recursive=False):
+        yield body_tr_generator(tr_tag)
+
+
+async def extract_table_body_columns(table_body: Tag) -> list[list[Tag]]:
+    columns_matrix: list[list[Tag]] = []
+
+    for tr_ind, tr_info in enumerate(body_table_generator(table_body)):
+        for td_ind, (td_tag, td_colspan, td_rowspan) in enumerate(tr_info):
+            for row_span in range(td_rowspan):
+                row_ind: int = tr_ind + row_span
+
+                try:
+                    columns_matrix[row_ind]
+                except IndexError:
+                    columns_matrix.append([])
+
+                for column_span in range(td_colspan):
+                    columns_matrix[row_ind].append(td_tag)
+
+    return columns_matrix

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/table_head_extractor.py

@@ -0,0 +1,50 @@
+from typing import Generator
+
+from bs4 import Tag, ResultSet
+
+from .errors import NoTableHeaderError
+from .types import ExtractorOptions
+from .utils import handle_maybe_async
+
+
+async def extract_table_head(table: Tag, *, options: ExtractorOptions) -> Tag:
+    heads: ResultSet[Tag] = table.find_all("thead", recursive=False)
+
+    if len(heads) == 0:
+        raise NoTableHeaderError
+    if len(heads) > 1:
+        return await handle_maybe_async(options.on_multiply_table_headers, heads)
+
+    return heads[0]
+
+
+def head_tr_generator(tr_tag: Tag) -> Generator[tuple[Tag, int, int], None, None]:
+    for th_tag in tr_tag.find_all("th", recursive=False):
+        th_colspan: int = int(th_tag.get("colspan") or 1)
+        th_rowspan: int = int(th_tag.get("rowspan") or 1)
+
+        yield th_tag, th_colspan, th_rowspan
+
+
+def head_table_generator(table_head: Tag) -> Generator[Generator[tuple[Tag, int, int], None, None], None, None]:
+    for tr_tag in table_head.find_all("tr", recursive=False):
+        yield head_tr_generator(tr_tag)
+
+
+async def extract_table_head_columns(table_head: Tag) -> list[list[Tag]]:
+    columns_matrix: list[list[Tag]] = []
+
+    for tr_ind, tr_info in enumerate(head_table_generator(table_head)):
+        for th_ind, (th_tag, th_colspan, th_rowspan) in enumerate(tr_info):
+            for row_span in range(th_rowspan):
+                row_ind: int = tr_ind + row_span
+
+                try:
+                    columns_matrix[row_ind]
+                except IndexError:
+                    columns_matrix.append([])
+
+                for column_span in range(th_colspan):
+                    columns_matrix[row_ind].append(th_tag)
+
+    return columns_matrix

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/tables_extractor.py

@@ -0,0 +1,48 @@
+from bs4 import BeautifulSoup, Tag, ResultSet
+
+from .def_funcs import MatrixizedTable
+from .errors import NoTableHeaderError, NoTableBodyError
+from .table_body_extractor import extract_table_body_columns, extract_table_body
+from .table_head_extractor import extract_table_head, extract_table_head_columns
+from .types import ExtractorOptions
+from .utils import get_page_bs4, handle_maybe_async
+
+
+async def matrixize_table(table: Tag, options: ExtractorOptions) -> MatrixizedTable:
+    head: Tag = await extract_table_head(table, options=options)
+    head_columns: list[list[Tag]] = await extract_table_head_columns(head)
+
+    body: Tag = await extract_table_body(table, options=options)
+    body_columns: list[list[Tag]] = await extract_table_body_columns(body)
+
+    return MatrixizedTable(
+        head=head_columns,
+        body=body_columns
+    )
+
+
+async def extract_tables(page_bs4: BeautifulSoup) -> ResultSet[Tag]:
+    tables: ResultSet[Tag] = page_bs4.find_all("table", recursive=False)
+
+    return tables
+
+
+async def matrixize_tables_from_page(url: str, *, options: ExtractorOptions | None = None) -> list[MatrixizedTable]:
+    if options is None:
+        options = ExtractorOptions()
+
+    page_bs4: BeautifulSoup = await get_page_bs4(url)
+    tables: ResultSet[Tag] = await extract_tables(page_bs4)
+
+    matrixized_tables: list[MatrixizedTable] = []
+    for table in tables:
+        try:
+            matrixized_table: MatrixizedTable = await matrixize_table(table, options=options)
+
+            matrixized_tables.append(matrixized_table)
+        except NoTableHeaderError:
+            await handle_maybe_async(options.on_table_no_header, table, matrixized_tables)
+        except NoTableBodyError:
+            await handle_maybe_async(options.on_table_no_body, table, matrixized_tables)
+
+    return matrixized_tables

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/types.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+from typing import Callable, Any, Never, Sequence
+
+from bs4 import Tag
+
+from .def_funcs import MatrixizedTable, on_table_no_header_def, on_table_no_body_def, on_multiply_table_headers_def, \
+    on_multiply_table_bodies_def
+
+
+@dataclass(frozen=True, kw_only=True)
+class ExtractorOptions:
+    on_table_no_header: Callable[[Tag, Sequence[MatrixizedTable]], Any] = on_table_no_header_def
+    on_table_no_body: Callable[[Tag, Sequence[MatrixizedTable]], Any] = on_table_no_body_def
+    on_multiply_table_headers: Callable[[Sequence[Tag]], Tag | Never] = on_multiply_table_headers_def
+    on_multiply_table_bodies: Callable[[Sequence[Tag]], Tag | Never] = on_multiply_table_bodies_def

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer/utils.py

@@ -0,0 +1,30 @@
+import inspect
+from typing import Coroutine, TypeVar, Awaitable, Callable
+
+from aiohttp import ClientSession
+from bs4 import BeautifulSoup
+
+
+async def get_page_bs4(url: str) -> BeautifulSoup:
+    async with ClientSession() as session:
+        async with session.get(url) as response:
+            return BeautifulSoup(await response.text(), "html.parser")
+
+
+T = TypeVar("T")
+
+
+async def handle_maybe_async(func: Coroutine[..., ..., T] | Callable[..., T | Awaitable[T]] | T, *args, **kwargs) -> T:
+    if inspect.iscoroutinefunction(func):
+        return await func(*args, **kwargs)
+    if inspect.iscoroutine(func):
+        return await func
+    if not inspect.isfunction(func):
+        return func
+
+    result: T = func(*args, **kwargs)
+
+    if inspect.isawaitable(result):
+        return await result
+
+    return result

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: sveden-table-matrixizer
+Version: 1.0.0
+Summary: Module for convert tables from HTML-pages (/sveden) to matrix of bs4 tags
+Author: BestTvGU
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4==4.14.3
+Requires-Dist: aiohttp==3.13.5
+Dynamic: license-file
+
+# sveden-table-matrixizer
+
+**Extract and matrixize HTML tables from Russian educational organization pages (`/sveden`) with full colspan/rowspan
+support.**
+
+`sveden-table-matrixizer` is an asynchronous Python library that parses tables found on `/sveden` (сведения об
+образовательной организации) pages, expands `colspan` and `rowspan` attributes into clean two-dimensional matrices, and
+returns structured `head` and `body` cell grids. It gives you full control over edge cases via configurable callbacks.
+
+## Features
+
+- **Async page fetching** using `aiohttp`.
+- **Full colspan/rowspan expansion** – cells spanning multiple rows and/or columns are duplicated into the matrix.
+- **Separate head and body matrix extraction** – each table yields a `head` matrix (from `<thead>`) and a `body`
+  matrix (from `<tbody>`).
+- **Customizable error handling** – replace default reactions to missing headers, missing bodies, or multiple `<thead>`/
+  `<tbody>` elements.
+- **Lightweight** – only depends on `aiohttp` and `beautifulsoup4`.
+- **Works with any HTML** – designed for `/sveden`, but usable on any page containing `<table>` elements.
+
+## Installation
+
+```bash
+pip install sveden-table-matrixizer
+```
+
+## Quick Start
+
+```python
+import asyncio
+from sveden_table_matrixizer import matrixize_tables_from_page
+
+
+async def main():
+    url = "https://example.edu/sveden/"
+    tables = await matrixize_tables_from_page(url)
+
+    for i, table in enumerate(tables):
+        print(f"Table {i + 1}:")
+        print("  Head rows:", len(table.head))
+        print("  Body rows:", len(table.body))
+        # Access cells as list[list[bs4.Tag]]
+
+
+asyncio.run(main())
+```
+
+Each `MatrixizedTable` contains:
+
+- `head: list[list[Tag]]` – rows of header cells _(each row is a list of `bs4.Tag`)_.
+- `body: list[list[Tag]]` – rows of body cells.
+
+## Handling Edge Cases
+
+By default, the extractor raises exceptions when a table lacks a header or body, or contains more than one `<thead>` /
+`<tbody>`. You can override this behavior with `ExtractorOptions`.
+
+```python
+from sveden_table_matrixizer import matrixize_tables_from_page, ExtractorOptions
+from sveden_table_matrixizer.def_funcs import MatrixizedTable
+
+
+def handle_missing_header(table_tag, collected_tables):
+    print(f"Skipping table without <thead>: {table_tag.get('id', 'no id')}")
+
+
+opts = ExtractorOptions(
+    on_table_no_header=handle_missing_header,
+    # other callbacks can be set similarly
+)
+
+tables = await matrixize_tables_from_page(url, options=opts)
+```
+
+You can also supply async callbacks – the library automatically detects and awaits them.
+
+## API Reference
+
+### `matrixize_tables_from_page(url, *, options=None)`
+
+- **Parameters:**
+    - `url` (`str`) – URL of the page to scrape.
+    - `options` (`ExtractorOptions`, optional) – configuration callbacks.
+- **Returns:** `list[MatrixizedTable]` – extracted and matrixized tables.
+
+### `ExtractorOptions`
+
+A frozen dataclass with the following fields (all optional):
+
+| Field                       | Type                                              | Default                           | Description                                                                           |
+|-----------------------------|---------------------------------------------------|-----------------------------------|---------------------------------------------------------------------------------------|
+| `on_table_no_header`        | `Callable[[Tag, Sequence[MatrixizedTable]], Any]` | no‑op                             | Called when a table has no `<thead>`                                                  |
+| `on_table_no_body`          | `Callable[[Tag, Sequence[MatrixizedTable]], Any]` | no‑op                             | Called when a table has no `<tbody>`                                                  |
+| `on_multiply_table_headers` | `Callable[[Sequence[Tag]], Tag \| Never]`         | raises `MultiplyTableHeaderError` | Called when more than one `<thead>` is found; must return a single `<thead>` element. |
+| `on_multiply_table_bodies`  | `Callable[[Sequence[Tag]], Tag \| Never]`         | raises `MultiplyTableBodyError`   | Called when more than one `<tbody>` is found; must return a single `<tbody>` element. |
+
+### `MatrixizedTable`
+
+```python
+@dataclass(frozen=True, kw_only=True)
+class MatrixizedTable:
+    head: list[list[Tag]]  # matrix of <th> tags
+    body: list[list[Tag]]  # matrix of <td> tags
+```
+
+### Exceptions
+
+- `NoTableHeaderError` – raised when `options.on_table_no_header` is not overridden.
+- `NoTableBodyError` – raised when `options.on_table_no_body` is not overridden.
+- `MultiplyTableHeaderError` – default reaction to multiple `<thead>` elements.
+- `MultiplyTableBodyError` – default reaction to multiple `<tbody>` elements.
+
+All exceptions are exported from `sveden_table_matrixizer.errors`.
+
+## How It Works
+
+1. The page is fetched with `aiohttp` and parsed by BeautifulSoup.
+2. All `<table>` tags are collected.
+3. For each table:
+    - The `<thead>` is located; if missing or duplicate, the appropriate callback is invoked.
+    - The `<tbody>` is located similarly.
+    - Header rows are expanded: each `<th>` with `colspan`/`rowspan` is replicated into the correct cells of a 2D list.
+    - The same expansion is applied to body rows using `<td>` elements.
+4. A `MatrixizedTable(head=..., body=...)` is created and added to the result list.
+
+## Dependencies
+
+- Python ≥ 3.11
+- [aiohttp](https://pypi.org/project/aiohttp/)
+- [beautifulsoup4](https://pypi.org/project/beautifulsoup4/)
+
+## License
+
+This project is licensed under the MIT License – see the source repository for details.

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+sveden_table_matrixizer/__init__.py
+sveden_table_matrixizer/def_funcs.py
+sveden_table_matrixizer/errors.py
+sveden_table_matrixizer/py.typed
+sveden_table_matrixizer/table_body_extractor.py
+sveden_table_matrixizer/table_head_extractor.py
+sveden_table_matrixizer/tables_extractor.py
+sveden_table_matrixizer/types.py
+sveden_table_matrixizer/utils.py
+sveden_table_matrixizer.egg-info/PKG-INFO
+sveden_table_matrixizer.egg-info/SOURCES.txt
+sveden_table_matrixizer.egg-info/dependency_links.txt
+sveden_table_matrixizer.egg-info/requires.txt
+sveden_table_matrixizer.egg-info/top_level.txt

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer.egg-info/requires.txt

@@ -0,0 +1,2 @@
+beautifulsoup4==4.14.3
+aiohttp==3.13.5

sveden_table_matrixizer-1.0.0/sveden_table_matrixizer.egg-info/top_level.txt

@@ -0,0 +1 @@
+sveden_table_matrixizer