ebiblio-client 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ebiblio/__init__.py ADDED
@@ -0,0 +1,13 @@
1
+ """Cliente de búsqueda para catálogos web basados en eBiblio."""
2
+
3
+ from .client import EbiblioClient, EbiblioError
4
+ from .models import Contributor, Medium, SearchResult, SearchResults
5
+
6
+ __all__ = [
7
+ "EbiblioClient",
8
+ "EbiblioError",
9
+ "Contributor",
10
+ "Medium",
11
+ "SearchResult",
12
+ "SearchResults",
13
+ ]
ebiblio/cli.py ADDED
@@ -0,0 +1,197 @@
1
+ """Interfaz de línea de comandos para ebiblio-client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import sys
8
+ from typing import Sequence
9
+
10
+ from .client import EbiblioClient, EbiblioError
11
+ from .models import SearchResult
12
+
13
+
14
+ def _build_parser() -> argparse.ArgumentParser:
15
+ parser = argparse.ArgumentParser(
16
+ prog="ebiblio",
17
+ description=(
18
+ "Busca libros, películas y otros recursos "
19
+ "en un catálogo eBiblio."
20
+ ),
21
+ )
22
+ parser.add_argument(
23
+ "url",
24
+ help="URL del catálogo (p. ej. https://madrid.ebiblio.es/)",
25
+ )
26
+ parser.add_argument(
27
+ "keywords",
28
+ nargs="?",
29
+ default="",
30
+ help="Palabras clave",
31
+ )
32
+ parser.add_argument(
33
+ "--page", type=int, default=1, help="Página que se consultará"
34
+ )
35
+ parser.add_argument(
36
+ "--all",
37
+ dest="all_pages",
38
+ action="store_true",
39
+ help="Recorrer todas las páginas",
40
+ )
41
+ parser.add_argument(
42
+ "--max-pages",
43
+ type=int,
44
+ default=100,
45
+ help="Límite de páginas para --all",
46
+ )
47
+ parser.add_argument(
48
+ "--timeout",
49
+ type=float,
50
+ default=20.0,
51
+ help="Tiempo máximo de espera en segundos",
52
+ )
53
+
54
+ parser.add_argument("--isbn")
55
+ parser.add_argument("--author")
56
+ parser.add_argument("--narrator")
57
+ parser.add_argument("--director")
58
+ parser.add_argument("--actor")
59
+ parser.add_argument("--publisher")
60
+ parser.add_argument("--collection-title")
61
+ parser.add_argument("--issued-on-range")
62
+ parser.add_argument("--language")
63
+ parser.add_argument("--audience")
64
+ parser.add_argument("--category")
65
+ parser.add_argument("--category-standard")
66
+ parser.add_argument("--nature")
67
+ parser.add_argument("--medium")
68
+ parser.add_argument("--sort-by")
69
+ parser.add_argument(
70
+ "--available",
71
+ action="store_true",
72
+ help="Limitar a títulos disponibles",
73
+ )
74
+ parser.add_argument(
75
+ "--json", action="store_true", help="Imprimir resultados como JSON"
76
+ )
77
+ return parser
78
+
79
+
80
+ def _filters_from_args(args: argparse.Namespace) -> dict[str, object]:
81
+ filters = {
82
+ "isbn": args.isbn,
83
+ "author": args.author,
84
+ "narrator": args.narrator,
85
+ "director": args.director,
86
+ "actor": args.actor,
87
+ "publisher": args.publisher,
88
+ "collection_title": args.collection_title,
89
+ "issued_on_range": args.issued_on_range,
90
+ "language": args.language,
91
+ "audience": args.audience,
92
+ "category": args.category,
93
+ "category_standard": args.category_standard,
94
+ "nature": args.nature,
95
+ "medium": args.medium,
96
+ "sort_by": args.sort_by,
97
+ }
98
+ selected = {
99
+ name: value
100
+ for name, value in filters.items()
101
+ if value is not None
102
+ }
103
+ if args.available:
104
+ selected["availability"] = True
105
+ return selected
106
+
107
+
108
+ def _print_result(item: SearchResult, index: int) -> None:
109
+ kind = item.resource_type or "Recurso"
110
+ print(f"{index}. {item.title} [{kind}]")
111
+ print(f" {item.url}")
112
+ for contributor in item.contributors:
113
+ print(
114
+ f" {contributor.role.capitalize()}: "
115
+ f"{', '.join(contributor.names)}"
116
+ )
117
+ if item.description:
118
+ print(f" {item.description}")
119
+ for medium in item.media:
120
+ details = [medium.format or "Medio"]
121
+ if medium.quality:
122
+ details.append(medium.quality)
123
+ if medium.availability:
124
+ details.append(medium.availability)
125
+ print(f" Medio: {' — '.join(details)}")
126
+
127
+
128
+ def main(argv: Sequence[str] | None = None) -> int:
129
+ """Punto de entrada del comando `ebiblio`."""
130
+ args = _build_parser().parse_args(argv)
131
+ filters = _filters_from_args(args)
132
+ try:
133
+ client = EbiblioClient(args.url, timeout=args.timeout)
134
+ if args.all_pages:
135
+ items = client.search_all(
136
+ args.keywords,
137
+ max_pages=args.max_pages,
138
+ **filters,
139
+ )
140
+ page_result = None
141
+ else:
142
+ page_result = client.search(
143
+ args.keywords,
144
+ page=args.page,
145
+ **filters,
146
+ )
147
+ items = page_result.items
148
+ except (EbiblioError, TypeError, ValueError) as exc:
149
+ print(f"ebiblio: {exc}", file=sys.stderr)
150
+ return 2
151
+
152
+ if args.json:
153
+ payload: dict[str, object] = {
154
+ "items": [_result_to_dict(item) for item in items]
155
+ }
156
+ if page_result is not None:
157
+ payload.update(
158
+ current_page=page_result.current_page,
159
+ page_numbers=page_result.page_numbers,
160
+ next_page_url=page_result.next_page_url,
161
+ )
162
+ else:
163
+ payload["all_pages"] = True
164
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
165
+ return 0
166
+
167
+ if not items:
168
+ print("No se encontraron recursos.")
169
+ else:
170
+ for index, item in enumerate(items, start=1):
171
+ _print_result(item, index)
172
+ if page_result and page_result.next_page_url:
173
+ print(f"Página siguiente: {page_result.next_page_url}")
174
+ if args.all_pages:
175
+ print(f"Total de recursos recuperados: {len(items)}")
176
+ return 0
177
+
178
+
179
+ def _result_to_dict(item: SearchResult) -> dict[str, object]:
180
+ """Serializa el NamedTuple a un objeto JSON de estructura legible."""
181
+ return {
182
+ "title": item.title,
183
+ "url": item.url,
184
+ "resource_type": item.resource_type,
185
+ "resource_id": item.resource_id,
186
+ "cover_url": item.cover_url,
187
+ "description": item.description,
188
+ "contributors": {
189
+ contributor.role: contributor.names
190
+ for contributor in item.contributors
191
+ },
192
+ "media": [medium._asdict() for medium in item.media],
193
+ }
194
+
195
+
196
+ if __name__ == "__main__":
197
+ raise SystemExit(main())
ebiblio/client.py ADDED
@@ -0,0 +1,162 @@
1
+ """Cliente HTTP de solo lectura para búsquedas en catálogos eBiblio."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from http.cookiejar import CookieJar
6
+ from typing import Any
7
+ from urllib.error import HTTPError, URLError
8
+ from urllib.parse import parse_qs, urlencode, urljoin, urlsplit, urlunsplit
9
+ from urllib.request import HTTPCookieProcessor, Request, build_opener
10
+
11
+ from .models import SearchResult, SearchResults
12
+ from .parser import parse_search_results
13
+
14
+
15
+ class EbiblioError(Exception):
16
+ """Error de red o de respuesta del catálogo."""
17
+
18
+
19
+ class EbiblioClient:
20
+ """Busca recursos en un sitio compatible con el catálogo eBiblio.
21
+
22
+ Ejemplo::
23
+
24
+ client = EbiblioClient("https://madrid.ebiblio.es/")
25
+ results = client.search("Mabuse", language="spa", nature="ebook")
26
+ for item in results.items:
27
+ print(item.title, item.authors, item.url)
28
+ """
29
+
30
+ _search_fields = {
31
+ "isbn",
32
+ "author",
33
+ "narrator",
34
+ "director",
35
+ "actor",
36
+ "publisher",
37
+ "collection_title",
38
+ "issued_on_range",
39
+ "language",
40
+ "audience",
41
+ "category",
42
+ "nature",
43
+ "medium",
44
+ "availability",
45
+ "category_standard",
46
+ "sort_by",
47
+ }
48
+
49
+ def __init__(
50
+ self,
51
+ url: str,
52
+ *,
53
+ timeout: float = 20.0,
54
+ user_agent: str = "ebiblio-client/0.1 (+https://www.python.org/)",
55
+ ) -> None:
56
+ parsed = urlsplit(url.strip())
57
+ if parsed.scheme not in {"http", "https"} or not parsed.netloc:
58
+ raise ValueError("La URL debe ser absoluta y usar http o https.")
59
+ if timeout <= 0:
60
+ raise ValueError("timeout debe ser mayor que cero.")
61
+ self.base_url = urlunsplit((parsed.scheme, parsed.netloc, "/", "", ""))
62
+ self.timeout = timeout
63
+ self.user_agent = user_agent
64
+ self._cookies = CookieJar()
65
+ self._opener = build_opener(HTTPCookieProcessor(self._cookies))
66
+
67
+ def _fetch(self, url: str) -> str:
68
+ request = Request(
69
+ url,
70
+ headers={
71
+ "User-Agent": self.user_agent,
72
+ "Accept": "text/html,application/xhtml+xml",
73
+ },
74
+ )
75
+ try:
76
+ with self._opener.open(request, timeout=self.timeout) as response:
77
+ charset = response.headers.get_content_charset() or "utf-8"
78
+ return response.read().decode(charset, errors="replace")
79
+ except (HTTPError, URLError, OSError) as exc:
80
+ raise EbiblioError(f"No se pudo consultar {url}: {exc}") from exc
81
+
82
+ def search(
83
+ self,
84
+ keywords: str = "",
85
+ *,
86
+ page: int = 1,
87
+ **filters: Any,
88
+ ) -> SearchResults:
89
+ """Ejecuta una búsqueda y devuelve los recursos de la página indicada.
90
+
91
+ Los filtros aceptan los nombres del formulario web (por ejemplo,
92
+ ``author``, ``language``, ``category``, ``nature``, ``medium`` y
93
+ ``availability``). También se admite ``q`` como alias de ``keywords``.
94
+ """
95
+ if page < 1:
96
+ raise ValueError("page debe ser un entero positivo.")
97
+ if "q" in filters:
98
+ if keywords:
99
+ raise TypeError("Usa keywords o q, pero no ambos.")
100
+ keywords = filters.pop("q")
101
+
102
+ unknown = set(filters) - self._search_fields
103
+ if unknown:
104
+ fields = ", ".join(sorted(unknown))
105
+ raise TypeError(f"Filtros no reconocidos: {fields}")
106
+
107
+ params: dict[str, str] = {
108
+ "category_standard": "ebiblio",
109
+ "page": str(page),
110
+ }
111
+ if keywords:
112
+ params["keywords"] = str(keywords)
113
+ for name, value in filters.items():
114
+ if value is None or value is False:
115
+ continue
116
+ if name == "availability" and value is True:
117
+ params[name] = "available"
118
+ else:
119
+ params[name] = str(value)
120
+
121
+ search_url = urljoin(self.base_url, "/resources")
122
+ request_url = f"{search_url}?{urlencode(params)}"
123
+ html = self._fetch(request_url)
124
+ parsed = parse_search_results(html, self.base_url)
125
+ next_page_url = parsed.next_page_url
126
+ return SearchResults(
127
+ items=parsed.items,
128
+ current_page=(
129
+ parsed.current_page
130
+ if parsed.current_page > 1 or page == 1
131
+ else page
132
+ ),
133
+ page_numbers=parsed.page_numbers,
134
+ next_page_url=next_page_url,
135
+ )
136
+
137
+ def search_all(
138
+ self,
139
+ keywords: str = "",
140
+ *,
141
+ max_pages: int = 100,
142
+ **filters: Any,
143
+ ) -> tuple[SearchResult, ...]:
144
+ """Recorre páginas siguientes hasta el final o ``max_pages``."""
145
+ if max_pages < 1:
146
+ raise ValueError("max_pages debe ser un entero positivo.")
147
+ results: list[SearchResult] = []
148
+ page = 1
149
+ while page <= max_pages:
150
+ current = self.search(keywords, page=page, **filters)
151
+ results.extend(current.items)
152
+ if not current.next_page_url:
153
+ break
154
+ next_page = parse_qs(
155
+ urlsplit(current.next_page_url).query
156
+ ).get("page", [])
157
+ page = (
158
+ int(next_page[0])
159
+ if next_page and next_page[0].isdigit()
160
+ else page + 1
161
+ )
162
+ return tuple(results)
ebiblio/models.py ADDED
@@ -0,0 +1,56 @@
1
+ """Modelos inmutables de datos devueltos por el cliente."""
2
+
3
+ from typing import NamedTuple
4
+
5
+
6
+ class Medium(NamedTuple):
7
+ """Una edición o medio disponible para un recurso del catálogo."""
8
+
9
+ format: str
10
+ quality: str | None = None
11
+ availability: str | None = None
12
+ availability_count: int | None = None
13
+ borrow_url: str | None = None
14
+ streaming: bool = False
15
+ accessible: bool = False
16
+
17
+
18
+ class Contributor(NamedTuple):
19
+ """Colaborador asociado a un recurso y sus nombres."""
20
+
21
+ role: str
22
+ names: tuple[str, ...]
23
+
24
+
25
+ class SearchResult(NamedTuple):
26
+ """Un libro, película u otro recurso del catálogo."""
27
+
28
+ title: str
29
+ url: str
30
+ resource_type: str | None = None
31
+ resource_id: str | None = None
32
+ cover_url: str | None = None
33
+ description: str | None = None
34
+ contributors: tuple[Contributor, ...] = ()
35
+ media: tuple[Medium, ...] = ()
36
+
37
+ @property
38
+ def authors(self) -> tuple[str, ...]:
39
+ """Devuelve los colaboradores etiquetados como autor."""
40
+ return next(
41
+ (
42
+ contributor.names
43
+ for contributor in self.contributors
44
+ if contributor.role == "autor"
45
+ ),
46
+ (),
47
+ )
48
+
49
+
50
+ class SearchResults(NamedTuple):
51
+ """Página de resultados e información para continuar la paginación."""
52
+
53
+ items: tuple[SearchResult, ...]
54
+ current_page: int = 1
55
+ page_numbers: tuple[int, ...] = ()
56
+ next_page_url: str | None = None