agoras-common 2.0.0__tar.gz

agoras_common-2.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: agoras-common
+Version: 2.0.0
+Summary: Common utilities and logging for Agoras
+Home-page: https://github.com/LuisAlejandro/agoras
+Author: Luis Alejandro Martínez Faneyth
+Author-email: luis@luisalejandro.org
+Keywords: utilities,logging,social networks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+Requires-Dist: requests==2.33.1
+Requires-Dist: beautifulsoup4==4.14.3
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+agoras-common
+=============
+
+Low-level utilities, logging, and shared constants for the Agoras ecosystem.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install agoras-common
+
+Contents
+--------
+
+- **Version Info**: ``__version__``, ``__author__``, ``__email__``, ``__url__``, ``__description__``
+- **Utilities**: Helper functions for URL manipulation, metadata parsing
+- **Logger**: Centralized logging configuration
+
+Usage
+-----
+
+.. code-block:: python
+
+   from agoras.common import __version__, logger, add_url_timestamp, parse_metatags
+
+   # Version info
+   print(f"Agoras version: {__version__}")
+
+   # Logger
+   logger.start()
+   logger.loglevel('INFO')
+   logger.info("Hello from Agoras!")
+
+   # URL utilities
+   timestamped_url = add_url_timestamp('https://example.com', '20260110')
+   print(timestamped_url)  # https://example.com?t=20260110
+
+   # Metatag parsing
+   metatags = parse_metatags('https://example.com')
+   print(metatags['title'], metatags['image'])
+
+Dependencies
+------------
+
+None (pure Python utilities)

agoras_common-2.0.0/README.rst

@@ -0,0 +1,46 @@
+agoras-common
+=============
+
+Low-level utilities, logging, and shared constants for the Agoras ecosystem.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install agoras-common
+
+Contents
+--------
+
+- **Version Info**: ``__version__``, ``__author__``, ``__email__``, ``__url__``, ``__description__``
+- **Utilities**: Helper functions for URL manipulation, metadata parsing
+- **Logger**: Centralized logging configuration
+
+Usage
+-----
+
+.. code-block:: python
+
+   from agoras.common import __version__, logger, add_url_timestamp, parse_metatags
+
+   # Version info
+   print(f"Agoras version: {__version__}")
+
+   # Logger
+   logger.start()
+   logger.loglevel('INFO')
+   logger.info("Hello from Agoras!")
+
+   # URL utilities
+   timestamped_url = add_url_timestamp('https://example.com', '20260110')
+   print(timestamped_url)  # https://example.com?t=20260110
+
+   # Metatag parsing
+   metatags = parse_metatags('https://example.com')
+   print(metatags['title'], metatags['image'])
+
+Dependencies
+------------
+
+None (pure Python utilities)

agoras_common-2.0.0/setup.cfg

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

agoras_common-2.0.0/setup.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+from setuptools import find_namespace_packages, setup
+
+setup(
+    name='agoras-common',
+    version='2.0.0',
+    author='Luis Alejandro Martínez Faneyth',
+    author_email='luis@luisalejandro.org',
+    url='https://github.com/LuisAlejandro/agoras',
+    description='Common utilities and logging for Agoras',
+    long_description=open('README.rst').read(),
+    long_description_content_type='text/x-rst',
+    packages=find_namespace_packages(where='src'),
+    package_dir={'': 'src'},
+    python_requires='>=3.10',
+    install_requires=[
+        'requests==2.33.1',
+        'beautifulsoup4==4.14.3',
+    ],
+    classifiers=[
+        'Development Status :: 5 - Production/Stable',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
+        'Natural Language :: English',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+        'Programming Language :: Python :: 3.13',
+        'Programming Language :: Python :: 3.14',
+    ],
+    keywords=['utilities', 'logging', 'social networks'],
+    zip_safe=False,
+)

agoras_common-2.0.0/src/agoras/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+# Namespace package for agoras
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

agoras_common-2.0.0/src/agoras/common/__init__.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+agoras.common
+=============
+
+Common utilities, logging, and shared constants for Agoras.
+
+This package provides low-level utilities used throughout the Agoras ecosystem:
+- Version and metadata information
+- Logging infrastructure
+- URL manipulation utilities
+- Web scraping utilities
+"""
+
+from .logger import ControlableLogger, logger
+from .utils import add_url_timestamp, parse_metatags
+from .version import __author__, __description__, __email__, __url__, __version__
+
+__all__ = [
+    '__version__',
+    '__author__',
+    '__email__',
+    '__url__',
+    '__description__',
+    'logger',
+    'ControlableLogger',
+    'add_url_timestamp',
+    'parse_metatags',
+]

agoras_common-2.0.0/src/agoras/common/logger.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+``agoras.core.logger`` is the global application logging module.
+
+All modules use the same global logging object. No messages will be emitted
+until the logger is started.
+"""
+
+import logging
+import sys
+from typing import cast
+
+levelNames = {
+    'CRITICAL': 50,
+    'ERROR': 40,
+    'WARN': 30,
+    'WARNING': 30,
+    'INFO': 20,
+    'DEBUG': 10,
+    'NOTSET': 0,
+}
+
+
+class ControlableLogger(logging.Logger):
+    """
+    This class represents a logger object that can be started and stopped.
+
+    It has a start method which allows you to specify a logging level.
+    The stop method halts output.
+    """
+
+    def __init__(self, name=''):
+        """
+        Initialize this ``ControlableLogger``.
+
+        The name defaults to the application name. Loggers with the same name
+        refer to the same underlying object. Names are hierarchical, e.g.
+        'parent.child' defines a logger that is a descendant of 'parent'.
+
+        :param name: a string containing the logger name.
+        :return: a ``ControlableLogger`` instance.
+
+        .. versionadded:: 0.1.0
+        """
+        # Initializing parent class
+        super(ControlableLogger, self).__init__(name)
+
+        self.parent = logging.root
+
+        #: Attribute ``disabled`` (boolean): Stores the current status of the
+        #: logger.
+        self.disabled = True
+        self.propagate = False
+
+        #: Attribute ``formatstring`` (string): Stores the string that
+        #: will be used to format the logger output.
+        self.formatstring = '[%(levelname)s] %(message)s'
+
+    def start(self, filename=None):
+        """
+        Start logging with this logger.
+
+        Until the logger is started, no messages will be emitted. This applies
+        to all loggers with the same name and any child loggers.
+
+        .. versionadded:: 0.1.0
+        """
+        if self.disabled:
+            sh = logging.StreamHandler(sys.stdout)
+            sh.setFormatter(logging.Formatter(self.formatstring))
+            self.addHandler(sh)
+            if filename:
+                fh = logging.FileHandler(filename, mode='w')
+                fh.setFormatter(logging.Formatter(self.formatstring))
+                self.addHandler(fh)
+            self.disabled = False
+
+    def stop(self):
+        """
+        Stop logging with this logger.
+
+        Remove available handlers and set disabled attribute to ``True``.
+
+        .. versionadded:: 0.1.0
+        """
+        if not self.disabled:
+            for h in list(self.handlers):
+                self.removeHandler(h)
+            self.disabled = True
+
+    def loglevel(self, level='INFO'):
+        """
+        Set the log level for this logger.
+
+        Messages less than the given priority level will be ignored. The
+        default level is 'INFO', which conforms to the *nix convention that
+        a successful run should produce no diagnostic output. Available levels
+        and their suggested meanings:
+
+        * ``NOTSET``: all messages are processed.
+        * ``DEBUG``: output useful for developers.
+        * ``INFO``: trace normal program flow, especially external
+                    interactions.
+        * ``WARNING``: an abnormal condition was detected that might need
+                       attention.
+        * ``ERROR``: an error was detected but execution continued.
+        * ``CRITICAL``: an error was detected and execution was halted.
+
+        :param level: a string containing the desired logging level.
+
+        .. versionadded:: 0.1.0
+        """
+        if not self.disabled:
+            self.setLevel(levelNames[level])
+
+
+logging.setLoggerClass(ControlableLogger)
+logger = cast(ControlableLogger, logging.getLogger(__name__.split('.')[0]))

agoras_common-2.0.0/src/agoras/common/utils.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+
+agoras.common.utils
+===================
+
+This module contains common and low level functions to all modules in agoras.
+
+"""
+
+
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+
+def add_url_timestamp(url, timestamp):
+    parsed = urlparse(url)
+    query = dict(parse_qs(str(parsed.query)))
+    query['t'] = timestamp
+    parsed = parsed._replace(query=urlencode(query))
+    return parsed.geturl()
+
+
+def metatag(tag):
+    return tag.name == "meta" \
+        and tag.has_attr("content") \
+        and (tag.has_attr("property") or tag.has_attr("name"))
+
+
+def find_metatags(url, search):
+    found = {}
+
+    response = requests.get(url, timeout=20)
+
+    if response.status_code != 200:
+        return found
+
+    soup = BeautifulSoup(response.content, 'html.parser')
+
+    for target in search:
+        found_meta_tag = soup.find_all(metatag)
+
+        if not found_meta_tag:
+            continue
+
+        for meta_tag in found_meta_tag:
+
+            prop = meta_tag.get("property", "")
+            name = meta_tag.get("name", "")
+
+            if prop == target or name == target:
+                found[target] = meta_tag.get("content", "")
+
+    return found
+
+
+def parse_metatags(url):
+
+    KNOWN_TAGS = [
+        "og:title",
+        "og:image",
+        "og:description",
+        "twitter:title",
+        "twitter:image",
+        "twitter:description",
+    ]
+
+    try:
+        data = find_metatags(url, KNOWN_TAGS)
+    except Exception:
+        data = {}
+
+    return {
+        "title": data.get("og:title", data.get("twitter:title", "")),
+        "image": data.get("og:image", data.get("twitter:image", "")),
+        "description": data.get("og:description", data.get("twitter:description", "")),
+    }

agoras_common-2.0.0/src/agoras/common/version.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+agoras.common.version
+=====================
+
+Version and metadata information for Agoras.
+
+This module serves as the single source of truth for version info
+across all Agoras packages.
+"""
+
+__author__ = 'Luis Alejandro Martínez Faneyth'
+__email__ = 'luis@luisalejandro.org'
+__version__ = '2.0.0'
+__url__ = 'https://github.com/LuisAlejandro/agoras'
+__description__ = (
+    'A command line python utility to manage your social'
+    ' networks (Twitter, Facebook, Instagram, LinkedIn, Discord, '
+    'YouTube, TikTok, Telegram, Threads, WhatsApp, and X)'
+)

agoras_common-2.0.0/src/agoras_common.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: agoras-common
+Version: 2.0.0
+Summary: Common utilities and logging for Agoras
+Home-page: https://github.com/LuisAlejandro/agoras
+Author: Luis Alejandro Martínez Faneyth
+Author-email: luis@luisalejandro.org
+Keywords: utilities,logging,social networks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+Requires-Dist: requests==2.33.1
+Requires-Dist: beautifulsoup4==4.14.3
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+agoras-common
+=============
+
+Low-level utilities, logging, and shared constants for the Agoras ecosystem.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install agoras-common
+
+Contents
+--------
+
+- **Version Info**: ``__version__``, ``__author__``, ``__email__``, ``__url__``, ``__description__``
+- **Utilities**: Helper functions for URL manipulation, metadata parsing
+- **Logger**: Centralized logging configuration
+
+Usage
+-----
+
+.. code-block:: python
+
+   from agoras.common import __version__, logger, add_url_timestamp, parse_metatags
+
+   # Version info
+   print(f"Agoras version: {__version__}")
+
+   # Logger
+   logger.start()
+   logger.loglevel('INFO')
+   logger.info("Hello from Agoras!")
+
+   # URL utilities
+   timestamped_url = add_url_timestamp('https://example.com', '20260110')
+   print(timestamped_url)  # https://example.com?t=20260110
+
+   # Metatag parsing
+   metatags = parse_metatags('https://example.com')
+   print(metatags['title'], metatags['image'])
+
+Dependencies
+------------
+
+None (pure Python utilities)

agoras_common-2.0.0/src/agoras_common.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.rst
+setup.py
+src/agoras/__init__.py
+src/agoras/common/__init__.py
+src/agoras/common/logger.py
+src/agoras/common/utils.py
+src/agoras/common/version.py
+src/agoras_common.egg-info/PKG-INFO
+src/agoras_common.egg-info/SOURCES.txt
+src/agoras_common.egg-info/dependency_links.txt
+src/agoras_common.egg-info/not-zip-safe
+src/agoras_common.egg-info/requires.txt
+src/agoras_common.egg-info/top_level.txt
+tests/test_logger.py
+tests/test_utils.py

agoras_common-2.0.0/src/agoras_common.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agoras_common-2.0.0/src/agoras_common.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

agoras_common-2.0.0/src/agoras_common.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests==2.33.1
+beautifulsoup4==4.14.3

agoras_common-2.0.0/src/agoras_common.egg-info/top_level.txt

@@ -0,0 +1 @@
+agoras

agoras_common-2.0.0/tests/test_logger.py

@@ -0,0 +1,243 @@
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import doctest
+import io
+import logging
+import os
+import sys
+import tempfile
+import unittest
+
+from agoras.common.logger import levelNames, logger
+
+
+class TestLogger(unittest.TestCase):
+
+    def setUp(self):
+        # Ensure logger is stopped before each test
+        if not logger.disabled:
+            logger.stop()
+
+    def tearDown(self):
+        # Clean up after each test
+        if not logger.disabled:
+            logger.stop()
+
+    def test_01_default_level(self):
+        """Test logger default state."""
+        # Logger should be disabled initially
+        self.assertTrue(logger.disabled)
+
+    def test_start_without_filename(self):
+        """Test starting logger without filename parameter."""
+        logger.start()
+
+        # Logger should be enabled
+        self.assertFalse(logger.disabled)
+
+        # Should have exactly one handler (StreamHandler)
+        self.assertEqual(len(logger.handlers), 1)
+        self.assertIsInstance(logger.handlers[0], logging.StreamHandler)
+
+    def test_start_with_filename(self):
+        """Test starting logger with filename parameter."""
+        with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:
+            temp_filename = f.name
+
+        try:
+            logger.start(filename=temp_filename)
+
+            # Logger should be enabled
+            self.assertFalse(logger.disabled)
+
+            # Should have two handlers (StreamHandler + FileHandler)
+            self.assertEqual(len(logger.handlers), 2)
+
+            # Check handler types
+            handler_types = [type(h).__name__ for h in logger.handlers]
+            self.assertIn('StreamHandler', handler_types)
+            self.assertIn('FileHandler', handler_types)
+
+            logger.stop()
+        finally:
+            # Clean up temp file
+            if os.path.exists(temp_filename):
+                os.remove(temp_filename)
+
+    def test_start_when_already_started(self):
+        """Test that starting an already started logger doesn't add duplicate handlers."""
+        logger.start()
+        initial_handler_count = len(logger.handlers)
+
+        # Try to start again
+        logger.start()
+
+        # Handler count should not increase
+        self.assertEqual(len(logger.handlers), initial_handler_count)
+
+    def test_stop_after_start(self):
+        """Test stopping logger after starting."""
+        logger.start()
+        self.assertFalse(logger.disabled)
+        self.assertGreater(len(logger.handlers), 0)
+
+        logger.stop()
+
+        # Logger should be disabled
+        self.assertTrue(logger.disabled)
+
+        # All handlers should be removed
+        self.assertEqual(len(logger.handlers), 0)
+
+    def test_stop_when_already_stopped(self):
+        """Test stopping an already stopped logger."""
+        # Ensure logger is stopped
+        if not logger.disabled:
+            logger.stop()
+
+        # Should not raise error
+        logger.stop()
+
+        # Should still be disabled
+        self.assertTrue(logger.disabled)
+
+    def test_stop_clears_all_handlers(self):
+        """Test that stop clears all handlers including file handler."""
+        with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:
+            temp_filename = f.name
+
+        try:
+            logger.start(filename=temp_filename)
+            self.assertEqual(len(logger.handlers), 2)
+
+            logger.stop()
+
+            # All handlers should be cleared
+            self.assertEqual(len(logger.handlers), 0)
+        finally:
+            if os.path.exists(temp_filename):
+                os.remove(temp_filename)
+
+    def test_loglevel_sets_debug(self):
+        """Test setting log level to DEBUG."""
+        logger.start()
+        logger.loglevel('DEBUG')
+
+        self.assertEqual(logger.level, 10)
+
+        logger.stop()
+
+    def test_loglevel_sets_info(self):
+        """Test setting log level to INFO."""
+        logger.start()
+        logger.loglevel('INFO')
+
+        self.assertEqual(logger.level, 20)
+
+        logger.stop()
+
+    def test_loglevel_sets_warning(self):
+        """Test setting log level to WARNING."""
+        logger.start()
+        logger.loglevel('WARNING')
+
+        self.assertEqual(logger.level, 30)
+
+        logger.stop()
+
+    def test_loglevel_sets_error(self):
+        """Test setting log level to ERROR."""
+        logger.start()
+        logger.loglevel('ERROR')
+
+        self.assertEqual(logger.level, 40)
+
+        logger.stop()
+
+    def test_loglevel_sets_critical(self):
+        """Test setting log level to CRITICAL."""
+        logger.start()
+        logger.loglevel('CRITICAL')
+
+        self.assertEqual(logger.level, 50)
+
+        logger.stop()
+
+    def test_loglevel_sets_notset(self):
+        """Test setting log level to NOTSET."""
+        logger.start()
+        logger.loglevel('NOTSET')
+
+        self.assertEqual(logger.level, 0)
+
+        logger.stop()
+
+    def test_loglevel_on_disabled_logger(self):
+        """Test that loglevel has no effect on disabled logger."""
+        # Ensure logger is disabled
+        if not logger.disabled:
+            logger.stop()
+
+        initial_level = logger.level
+
+        # Try to set level on disabled logger
+        logger.loglevel('DEBUG')
+
+        # Level should not change
+        self.assertEqual(logger.level, initial_level)
+
+    def test_logger_format_string(self):
+        """Test that logger uses correct format string."""
+        self.assertEqual(logger.formatstring, '[%(levelname)s] %(message)s')
+
+    def test_logger_actually_logs_messages(self):
+        """Test that logger actually outputs log messages."""
+        # Create a string buffer to capture output
+        string_buffer = io.StringIO()
+
+        # Create a handler that writes to our buffer
+        handler = logging.StreamHandler(string_buffer)
+        handler.setFormatter(logging.Formatter(logger.formatstring))
+
+        # Manually add handler (simulating start behavior)
+        logger.addHandler(handler)
+        logger.disabled = False
+        logger.setLevel(logging.INFO)
+
+        # Log a message
+        logger.info('Test message')
+
+        # Get output
+        output = string_buffer.getvalue()
+
+        # Verify message appears with correct format
+        self.assertIn('[INFO] Test message', output)
+
+        # Clean up
+        logger.removeHandler(handler)
+        logger.disabled = True
+
+
+def load_tests(loader, tests, pattern):
+    tests.addTests(doctest.DocTestSuite('agoras.common.logger'))
+    return tests
+
+
+if __name__ == '__main__':
+    sys.exit(unittest.main())

agoras_common-2.0.0/tests/test_utils.py

@@ -0,0 +1,259 @@
+# -*- coding: utf-8 -*-
+#
+# Please refer to AUTHORS.rst for a complete list of Copyright holders.
+# Copyright (C) 2022-2026, Agoras Developers.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import doctest
+import sys
+import unittest
+from unittest.mock import Mock, patch
+
+from bs4 import BeautifulSoup
+
+from agoras.common.utils import add_url_timestamp, find_metatags, metatag, parse_metatags
+
+
+class TestAddUrlTimestamp(unittest.TestCase):
+    """Tests for add_url_timestamp function."""
+
+    def test_add_timestamp_to_url_without_query(self):
+        """Test adding timestamp to URL without query parameters."""
+        url = "https://example.com"
+        timestamp = 12345
+        result = add_url_timestamp(url, timestamp)
+        self.assertIn("t=12345", result)
+        self.assertTrue(result.startswith("https://example.com?"))
+
+    def test_add_timestamp_to_url_with_existing_query(self):
+        """Test adding timestamp to URL with existing query parameters."""
+        url = "https://example.com?foo=bar"
+        timestamp = 67890
+        result = add_url_timestamp(url, timestamp)
+        # parse_qs returns lists, so foo will be encoded as ['bar']
+        self.assertIn("foo=", result)
+        self.assertIn("t=67890", result)
+        self.assertTrue(result.startswith("https://example.com?"))
+
+    def test_replace_existing_timestamp(self):
+        """Test replacing existing timestamp parameter."""
+        url = "https://example.com?t=111&foo=bar"
+        timestamp = 999
+        result = add_url_timestamp(url, timestamp)
+        self.assertIn("t=999", result)
+        self.assertIn("foo=", result)
+        self.assertNotIn("t=111", result)
+
+    def test_url_with_fragment(self):
+        """Test URL with fragment."""
+        url = "https://example.com#section"
+        timestamp = 55555
+        result = add_url_timestamp(url, timestamp)
+        self.assertIn("t=55555", result)
+        self.assertIn("#section", result)
+
+
+class TestMetatag(unittest.TestCase):
+    """Tests for metatag function."""
+
+    def test_valid_meta_tag_with_property(self):
+        """Test with valid meta tag that has property attribute."""
+        html = '<meta property="og:title" content="Test">'
+        soup = BeautifulSoup(html, 'html.parser')
+        tag = soup.find('meta')
+        result = metatag(tag)
+        self.assertTrue(result)
+
+    def test_valid_meta_tag_with_name(self):
+        """Test with valid meta tag that has name attribute."""
+        html = '<meta name="description" content="Test">'
+        soup = BeautifulSoup(html, 'html.parser')
+        tag = soup.find('meta')
+        result = metatag(tag)
+        self.assertTrue(result)
+
+    def test_invalid_tag_not_meta(self):
+        """Test with invalid tag (not meta)."""
+        html = '<div content="Test">Text</div>'
+        soup = BeautifulSoup(html, 'html.parser')
+        tag = soup.find('div')
+        result = metatag(tag)
+        self.assertFalse(result)
+
+    def test_meta_tag_without_content(self):
+        """Test with meta tag without content attribute."""
+        html = '<meta property="og:title">'
+        soup = BeautifulSoup(html, 'html.parser')
+        tag = soup.find('meta')
+        result = metatag(tag)
+        self.assertFalse(result)
+
+    def test_meta_tag_without_property_or_name(self):
+        """Test with meta tag without property or name attribute."""
+        html = '<meta content="Test">'
+        soup = BeautifulSoup(html, 'html.parser')
+        tag = soup.find('meta')
+        result = metatag(tag)
+        self.assertFalse(result)
+
+
+class TestFindMetatags(unittest.TestCase):
+    """Tests for find_metatags function."""
+
+    @patch('agoras.common.utils.requests.get')
+    def test_successful_meta_tag_extraction(self, mock_get):
+        """Test successful meta tag extraction."""
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.content = b'<html><meta property="og:title" content="My Title"></html>'
+        mock_get.return_value = mock_response
+
+        result = find_metatags('https://example.com', ['og:title'])
+        self.assertEqual(result, {'og:title': 'My Title'})
+
+    @patch('agoras.common.utils.requests.get')
+    def test_multiple_meta_tags(self, mock_get):
+        """Test extraction of multiple meta tags."""
+        html = '''<html>
+            <meta property="og:title" content="Title">
+            <meta property="og:image" content="image.jpg">
+            <meta name="twitter:description" content="Description">
+        </html>'''
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.content = html.encode()
+        mock_get.return_value = mock_response
+
+        result = find_metatags('https://example.com',
+                               ['og:title', 'og:image', 'twitter:description'])
+        self.assertEqual(result['og:title'], 'Title')
+        self.assertEqual(result['og:image'], 'image.jpg')
+        self.assertEqual(result['twitter:description'], 'Description')
+
+    @patch('agoras.common.utils.requests.get')
+    def test_non_200_status_code(self, mock_get):
+        """Test with non-200 status code."""
+        mock_response = Mock()
+        mock_response.status_code = 404
+        mock_get.return_value = mock_response
+
+        result = find_metatags('https://example.com', ['og:title'])
+        self.assertEqual(result, {})
+
+    @patch('agoras.common.utils.requests.get')
+    def test_html_without_matching_meta_tags(self, mock_get):
+        """Test HTML without matching meta tags."""
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.content = b'<html><p>No meta tags here</p></html>'
+        mock_get.return_value = mock_response
+
+        result = find_metatags('https://example.com', ['og:title'])
+        self.assertEqual(result, {})
+
+    @patch('agoras.common.utils.requests.get')
+    def test_meta_tags_with_name_attribute(self, mock_get):
+        """Test meta tags with name attribute."""
+        html = '<html><meta name="twitter:title" content="Twitter Title"></html>'
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.content = html.encode()
+        mock_get.return_value = mock_response
+
+        result = find_metatags('https://example.com', ['twitter:title'])
+        self.assertEqual(result, {'twitter:title': 'Twitter Title'})
+
+
+class TestParseMetatags(unittest.TestCase):
+    """Tests for parse_metatags function."""
+
+    @patch('agoras.common.utils.find_metatags')
+    def test_with_open_graph_tags(self, mock_find):
+        """Test with Open Graph tags."""
+        mock_find.return_value = {
+            'og:title': 'OG Title',
+            'og:image': 'og.jpg',
+            'og:description': 'OG Desc'
+        }
+
+        result = parse_metatags('https://example.com')
+        self.assertEqual(result, {
+            'title': 'OG Title',
+            'image': 'og.jpg',
+            'description': 'OG Desc'
+        })
+
+    @patch('agoras.common.utils.find_metatags')
+    def test_with_twitter_tags_fallback(self, mock_find):
+        """Test with Twitter tags as fallback."""
+        mock_find.return_value = {
+            'twitter:title': 'Twitter Title',
+            'twitter:image': 'twitter.jpg',
+            'twitter:description': 'Twitter Desc'
+        }
+
+        result = parse_metatags('https://example.com')
+        self.assertEqual(result, {
+            'title': 'Twitter Title',
+            'image': 'twitter.jpg',
+            'description': 'Twitter Desc'
+        })
+
+    @patch('agoras.common.utils.find_metatags')
+    def test_with_mixed_tags(self, mock_find):
+        """Test with mixed OG and Twitter tags."""
+        mock_find.return_value = {
+            'og:title': 'OG Title',
+            'twitter:image': 'twitter.jpg',
+            'og:description': 'OG Desc'
+        }
+
+        result = parse_metatags('https://example.com')
+        self.assertEqual(result['title'], 'OG Title')
+        self.assertEqual(result['image'], 'twitter.jpg')
+        self.assertEqual(result['description'], 'OG Desc')
+
+    @patch('agoras.common.utils.find_metatags')
+    def test_with_no_tags_found(self, mock_find):
+        """Test with no tags found."""
+        mock_find.return_value = {}
+
+        result = parse_metatags('https://example.com')
+        self.assertEqual(result, {
+            'title': '',
+            'image': '',
+            'description': ''
+        })
+
+    @patch('agoras.common.utils.find_metatags')
+    def test_exception_handling(self, mock_find):
+        """Test exception handling."""
+        mock_find.side_effect = Exception('Network error')
+
+        result = parse_metatags('https://example.com')
+        self.assertEqual(result, {
+            'title': '',
+            'image': '',
+            'description': ''
+        })
+
+
+def load_tests(loader, tests, pattern):
+    tests.addTests(doctest.DocTestSuite('agoras.common.utils'))
+    return tests
+
+
+if __name__ == '__main__':
+    sys.exit(unittest.main())