agoras-common 2.0.0__py3-none-any.whl

agoras/__init__.py

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

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+agoras/__init__.py,sha256=BizfjbmRwkeL71J-UJWv3xvnQ0jUnmi2sSDBeere0JM,120
+agoras/common/__init__.py,sha256=DwQEiKi8V0UWdQOQxEtIAke25pwvwsy8smoFeG_uSwg,1445
+agoras/common/logger.py,sha256=OlHM1TPQ9-eN5P5DevhjHKiiIcEbrdsoUYqmjCrMtlA,4467
+agoras/common/utils.py,sha256=Pk2Pb4mUh5PyOLw7szh89dU5FWch7-6fnaC7uCg5lBE,2532
+agoras/common/version.py,sha256=SmMFDcfHAKf5Dz_vDKrKh3zcgv92x6_rPrnefRbBe08,1337
+agoras_common-2.0.0.dist-info/METADATA,sha256=cTNh8SDaH3YlxUaHa-4Y_Xg_O154_G6TAffGUl7zxgs,2184
+agoras_common-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agoras_common-2.0.0.dist-info/top_level.txt,sha256=lpSbQnkePldQbtolks5qCcv_l_n22drGde6Jt-6ES_0,7
+agoras_common-2.0.0.dist-info/RECORD,,

agoras_common-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agoras_common-2.0.0.dist-info/top_level.txt

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