unibo-toolkit 0.4.0__tar.gz

unibo_toolkit-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vadym Teliatnyk
+
+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.

unibo_toolkit-0.4.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: unibo-toolkit
+Version: 0.4.0
+Summary: Python toolkit for scraping and accessing University of Bologna data
+Author-email: Vadym Teliatnyk <vadym.teliatnyk@komo4ek.me>
+License: MIT
+Requires-Python: <4.0,>=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4<5.0.0,>=4.9.0
+Requires-Dist: aiohttp<4.0.0,>=3.8.0
+Requires-Dist: lxml<6.0.0,>=4.9.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Dynamic: license-file
+
+# UniBo Toolkit
+
+Python toolkit for University of Bologna data scraping.

unibo_toolkit-0.4.0/README.md

@@ -0,0 +1,3 @@
+# UniBo Toolkit
+
+Python toolkit for University of Bologna data scraping.

unibo_toolkit-0.4.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "unibo-toolkit"
+version = "0.4.0"
+description = "Python toolkit for scraping and accessing University of Bologna data"
+authors = [
+    {name = "Vadym Teliatnyk", email = "vadym.teliatnyk@komo4ek.me"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8,<4.0"
+dependencies = [
+    "beautifulsoup4>=4.9.0,<5.0.0",
+    "aiohttp>=3.8.0,<4.0.0",
+    "lxml>=4.9.0,<6.0.0",
+    "python-dotenv>=1.0.0,<2.0.0"
+]
+
+[dependency-groups]
+dev = [
+    "black[d]>=24.0.0,<26.0.0",
+    "pytest>=7.0.0,<9.0.0",
+    "pytest-asyncio>=0.21.0,<1.0.0",
+    "mypy>=1.0.0,<2.0.0"
+]
+
+[tool.black]
+line-length = 100
+target-version = ['py38', 'py39', 'py310', 'py311', 'py312', 'py313']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+  | tests/research
+  | \.github
+)/
+'''
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

unibo_toolkit-0.4.0/setup.cfg

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

unibo_toolkit-0.4.0/src/unibo_toolkit/__init__.py

@@ -0,0 +1,38 @@
+"""UniBo Toolkit - Python library for University of Bologna data scraping."""
+
+from unibo_toolkit.clients import HTTPClient
+from unibo_toolkit.enums import AccessType, Area, Campus, CourseType, Language
+from unibo_toolkit.exceptions import (
+    CourseNotFoundError,
+    InvalidAreaError,
+    ScraperError,
+    UniboToolkitError,
+    UnsupportedLanguageError,
+)
+from unibo_toolkit.logging import setup_logging
+from unibo_toolkit.models import AreaInfo, Bachelor, BaseCourse, Master, SingleCycleMaster
+from unibo_toolkit.scrapers import CourseScraper
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "__version__",
+    "HTTPClient",
+    "AccessType",
+    "Area",
+    "Campus",
+    "CourseType",
+    "Language",
+    "AreaInfo",
+    "Bachelor",
+    "BaseCourse",
+    "Master",
+    "SingleCycleMaster",
+    "CourseScraper",
+    "setup_logging",
+    "UniboToolkitError",
+    "UnsupportedLanguageError",
+    "CourseNotFoundError",
+    "InvalidAreaError",
+    "ScraperError",
+]

unibo_toolkit-0.4.0/src/unibo_toolkit/clients/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP clients for UniBo toolkit."""
+
+from unibo_toolkit.clients.http import HTTPClient
+
+__all__ = ["HTTPClient"]

unibo_toolkit-0.4.0/src/unibo_toolkit/clients/http.py

@@ -0,0 +1,93 @@
+"""HTTP client for making requests to UniBo website."""
+
+from typing import Any, Dict, Optional
+import aiohttp
+
+
+class HTTPClient:
+    """Async HTTP client for UniBo website requests.
+
+    Handles all HTTP communication with proper error handling,
+    timeouts, and user agent configuration.
+    """
+
+    DEFAULT_HEADERS = {
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "it-IT,it;q=0.9,en-US;q=0.8,en;q=0.7",
+    }
+
+    def __init__(
+        self,
+        timeout: int = 30,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        """Initialize HTTP client.
+
+        Args:
+            timeout: Request timeout in seconds
+            headers: Optional custom headers to merge with defaults
+        """
+        self.timeout = aiohttp.ClientTimeout(total=timeout)
+        self.headers = {**self.DEFAULT_HEADERS, **(headers or {})}
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        self._session = aiohttp.ClientSession(
+            timeout=self.timeout,
+            headers=self.headers,
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def get(self, url: str, params: Optional[Dict[str, Any]] = None, **kwargs) -> str:
+        """Perform GET request and return response text.
+
+        Args:
+            url: Target URL
+            params: Query parameters
+            **kwargs: Additional arguments for aiohttp request
+
+        Returns:
+            Response text content
+
+        Raises:
+            aiohttp.ClientError: On network or HTTP errors
+        """
+        if not self._session:
+            raise RuntimeError("HTTPClient must be used as async context manager")
+
+        async with self._session.get(url, params=params, **kwargs) as response:
+            response.raise_for_status()
+            return await response.text()
+
+    async def post(
+        self, url: str, data: Optional[Any] = None, json: Optional[Dict[str, Any]] = None, **kwargs
+    ) -> str:
+        """Perform POST request and return response text.
+
+        Args:
+            url: Target URL
+            data: Form data
+            json: JSON payload
+            **kwargs: Additional arguments for aiohttp request
+
+        Returns:
+            Response text content
+
+        Raises:
+            aiohttp.ClientError: On network or HTTP errors
+        """
+        if not self._session:
+            raise RuntimeError("HTTPClient must be used as async context manager")
+
+        async with self._session.post(url, data=data, json=json, **kwargs) as response:
+            response.raise_for_status()
+            return await response.text()

unibo_toolkit-0.4.0/src/unibo_toolkit/enums/__init__.py

@@ -0,0 +1,9 @@
+"""Enumerations for UniBo toolkit."""
+
+from unibo_toolkit.enums.access_type import AccessType
+from unibo_toolkit.enums.area import Area
+from unibo_toolkit.enums.campus import Campus
+from unibo_toolkit.enums.course_type import CourseType
+from unibo_toolkit.enums.language import Language
+
+__all__ = ["AccessType", "Area", "Campus", "CourseType", "Language"]

unibo_toolkit-0.4.0/src/unibo_toolkit/enums/access_type.py

@@ -0,0 +1,10 @@
+"""Access type enumeration."""
+
+from enum import Enum
+
+
+class AccessType(Enum):
+    """Enrollment access type for courses."""
+
+    OPEN = "libero"
+    LIMITED = "programmato"

unibo_toolkit-0.4.0/src/unibo_toolkit/enums/area.py

@@ -0,0 +1,47 @@
+"""Academic area enumeration."""
+
+from enum import Enum
+
+
+class Area(Enum):
+    """Academic areas/fields at UniBo.
+
+    Each area represents a broad category of study programs
+    with a unique identifier used in the UniBo website.
+    """
+
+    ECONOMIA_MANAGEMENT = (1, "Economia e management")
+    FARMACIA_BIOTECNOLOGIE = (2, "Farmacia e biotecnologie")
+    GIURISPRUDENZA = (3, "Giurisprudenza")
+    INGEGNERIA_ARCHITETTURA = (4, "Ingegneria e architettura")
+    LINGUE_LETTERATURE = (5, "Lingue e Letterature, Traduzione e Interpretazione")
+    MEDICINA_CHIRURGIA = (6, "Medicina e Chirurgia")
+    MEDICINA_VETERINARIA = (7, "Medicina veterinaria")
+    PSICOLOGIA = (8, "Psicologia")
+    SCIENZE = (9, "Scienze")
+    SCIENZE_AGRO_ALIMENTARI = (10, "Scienze agro-alimentari")
+    SCIENZE_EDUCAZIONE = (11, "Scienze dell'educazione e della formazione")
+    SCIENZE_MOTORIE = (12, "Scienze motorie")
+    SCIENZE_POLITICHE = (13, "Scienze politiche")
+    SCIENZE_STATISTICHE = (14, "Scienze Statistiche")
+    SOCIOLOGIA = (15, "Sociologia")
+    STUDI_UMANISTICI = (16, "Studi umanistici")
+
+    def __init__(self, area_id: int, title_it: str):
+        self.area_id = area_id
+        self.title_it = title_it
+
+    @classmethod
+    def from_id(cls, area_id: int):
+        """Get Area by ID.
+
+        Args:
+            area_id: Area identifier (1-16)
+
+        Returns:
+            Area enum value or None if not found
+        """
+        for area in cls:
+            if area.area_id == area_id:
+                return area
+        return None

unibo_toolkit-0.4.0/src/unibo_toolkit/enums/campus.py

@@ -0,0 +1,13 @@
+"""Campus location enumeration."""
+
+from enum import Enum
+
+
+class Campus(Enum):
+    """UniBo campus locations."""
+
+    BOLOGNA = "bologna"
+    CESENA = "cesena"
+    FORLI = "forli"
+    RAVENNA = "ravenna"
+    RIMINI = "rimini"

unibo_toolkit-0.4.0/src/unibo_toolkit/enums/course_type.py

@@ -0,0 +1,11 @@
+"""Course type enumeration."""
+
+from enum import Enum
+
+
+class CourseType(Enum):
+    """Types of degree courses available at UniBo."""
+
+    BACHELOR = "bachelor"
+    MASTER = "master"
+    SINGLE_CYCLE_MASTER = "single_cycle_master"

unibo_toolkit-0.4.0/src/unibo_toolkit/enums/language.py

@@ -0,0 +1,11 @@
+"""Language enumeration for UniBo courses."""
+
+from enum import Enum
+
+
+class Language(Enum):
+    """Language of instruction for courses."""
+
+    IT = "it"
+    EN = "en"
+    FR = "fr"

unibo_toolkit-0.4.0/src/unibo_toolkit/exceptions.py

@@ -0,0 +1,100 @@
+"""Custom exceptions for UniBo Toolkit."""
+
+from __future__ import annotations
+
+from typing import List
+
+
+class UniboToolkitError(Exception):
+    """Base exception for all UniBo Toolkit errors."""
+
+    pass
+
+
+class UnsupportedLanguageError(UniboToolkitError):
+    """Raised when an unsupported language is provided.
+
+    The UniBo website only supports Italian (IT) and English (EN) languages.
+    Other languages like French (FR) are not available.
+
+    Attributes:
+        language: The unsupported language that was provided
+        supported_languages: List of supported language codes
+    """
+
+    def __init__(self, language: str, supported_languages: List[str] = None):
+        """Initialize the exception.
+
+        Args:
+            language: The unsupported language code
+            supported_languages: Optional list of supported languages
+        """
+        self.language = language
+        self.supported_languages = supported_languages or ["IT", "EN"]
+
+        message = (
+            f"Unsupported language: '{language}'. "
+            f"Supported languages are: {', '.join(self.supported_languages)}"
+        )
+        super().__init__(message)
+
+
+class CourseNotFoundError(UniboToolkitError):
+    """Raised when a requested course cannot be found.
+
+    Attributes:
+        course_id: The ID of the course that was not found
+    """
+
+    def __init__(self, course_id: int):
+        """Initialize the exception.
+
+        Args:
+            course_id: The ID of the course that was not found
+        """
+        self.course_id = course_id
+        message = f"Course with ID {course_id} not found"
+        super().__init__(message)
+
+
+class InvalidAreaError(UniboToolkitError):
+    """Raised when an invalid academic area is provided.
+
+    Attributes:
+        area_id: The ID of the invalid area
+    """
+
+    def __init__(self, area_id: int):
+        """Initialize the exception.
+
+        Args:
+            area_id: The ID of the invalid area
+        """
+        self.area_id = area_id
+        message = f"Invalid area ID: {area_id}"
+        super().__init__(message)
+
+
+class ScraperError(UniboToolkitError):
+    """Raised when scraping operations fail.
+
+    Attributes:
+        url: The URL that failed to be scraped
+        reason: The reason for the failure
+    """
+
+    def __init__(self, url: str, reason: str = None):
+        """Initialize the exception.
+
+        Args:
+            url: The URL that failed
+            reason: Optional reason for the failure
+        """
+        self.url = url
+        self.reason = reason
+
+        message = f"Failed to scrape {url}"
+        if reason:
+            message += f": {reason}"
+
+        super().__init__(message)

unibo_toolkit-0.4.0/src/unibo_toolkit/logging.py

@@ -0,0 +1,90 @@
+"""Logging configuration for unibo_toolkit library."""
+
+import logging
+from typing import Any, Optional
+
+from unibo_toolkit.utils.custom_logger import CustomLogger
+
+_LOGGER_NAME = "UNIBO_TOOLKIT"
+_logger_configured = False
+
+
+def setup_logging(
+    level: int = logging.INFO,
+    format_string: Optional[str] = None,
+    handler: Optional[logging.Handler] = None,
+) -> None:
+    """Configure logging for unibo_toolkit library.
+
+    By default, the library uses a NullHandler (no output). Call this function
+    to enable logging to see debug information, warnings, and errors.
+
+    Args:
+        level: Log level - one of: DEBUG, INFO, WARNING, ERROR, CRITICAL
+        format_string: Custom log format string. If None, uses structured format
+        handler: Custom logging handler. If None, uses StreamHandler (console output)
+
+    Example:
+        Enable INFO level logging to console:
+        >>> import unibo_toolkit
+        >>> unibo_toolkit.setup_logging(level=logging.INFO)
+
+        Enable DEBUG level with custom format:
+        >>> unibo_toolkit.setup_logging(
+        ...     level=logging.DEBUG,
+        ...     format_string='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        ... )
+
+        Use custom handler (e.g., file logging):
+        >>> import logging
+        >>> file_handler = logging.FileHandler('unibo_toolkit.log')
+        >>> unibo_toolkit.setup_logging(level=logging.DEBUG, handler=file_handler)
+    """
+    global _logger_configured
+
+    logger = logging.getLogger(_LOGGER_NAME)
+    logger.setLevel(level)
+
+    # Remove existing handlers to avoid duplicates
+    logger.handlers.clear()
+
+    # Create handler if not provided
+    if handler is None:
+        handler = logging.StreamHandler()
+
+    # Set format - default to structured format for CustomLogger
+    if format_string is None:
+        format_string = "[%(levelname)s] %(name)s - %(message)s"
+
+    formatter = logging.Formatter(format_string)
+    handler.setFormatter(formatter)
+
+    logger.addHandler(handler)
+    _logger_configured = True
+
+
+def get_logger(name: str, **items: Any) -> CustomLogger:
+    """Get custom logger instance for a module.
+
+    This function returns a CustomLogger that formats messages as
+    structured logs with key-value pairs.
+
+    Args:
+        name: Module name (usually __name__)
+        **items: Default items to include in all log messages
+
+    Returns:
+        CustomLogger instance
+
+    Example:
+        >>> logger = get_logger(__name__)
+        >>> logger.info("Course fetched", course_id=6796)
+        # Output: msg="Course fetched" course_id="6796"
+    """
+    return CustomLogger(f"{_LOGGER_NAME}.{name}", **items)
+
+
+# Initialize default logger with NullHandler (no output by default)
+_default_logger = logging.getLogger(_LOGGER_NAME)
+_default_logger.addHandler(logging.NullHandler())
+_default_logger.setLevel(logging.WARNING)

unibo_toolkit-0.4.0/src/unibo_toolkit/models/__init__.py

@@ -0,0 +1,30 @@
+"""Data models for UniBo courses."""
+
+from unibo_toolkit.models.area_info import AreaInfo
+from unibo_toolkit.models.course import Bachelor, BaseCourse, Master, SingleCycleMaster
+from unibo_toolkit.models.curriculum import Curriculum
+from unibo_toolkit.models.timetable import (
+    AcademicYearTimetable,
+    Classroom,
+    CurriculumTimetable,
+    Subject,
+    Timetable,
+    TimetableCollection,
+    TimetableEvent,
+)
+
+__all__ = [
+    "AcademicYearTimetable",
+    "AreaInfo",
+    "Bachelor",
+    "BaseCourse",
+    "Classroom",
+    "Curriculum",
+    "CurriculumTimetable",
+    "Master",
+    "SingleCycleMaster",
+    "Subject",
+    "Timetable",
+    "TimetableCollection",
+    "TimetableEvent",
+]

unibo_toolkit-0.4.0/src/unibo_toolkit/models/area_info.py

@@ -0,0 +1,20 @@
+"""Area information model."""
+
+from dataclasses import dataclass
+
+from unibo_toolkit.enums import Area, CourseType
+
+
+@dataclass
+class AreaInfo:
+    """Information about an academic area.
+
+    Attributes:
+        area: Academic area enum
+        course_count: Number of courses in this area
+        course_type: Type of courses (Bachelor/Master/SingleCycleMaster)
+    """
+
+    area: Area
+    course_count: int
+    course_type: CourseType