winipedia-utils 0.1.0__py3-none-any.whl

winipedia_utils/testing/tests/base/fixtures/scopes/session.py

@@ -0,0 +1,224 @@
+"""Session-level test fixtures and utilities.
+
+This module provides fixtures and test functions that operate at the session scope,
+ensuring that project-wide conventions are followed and that the overall project
+structure is correct. These fixtures are automatically applied to the test session
+through pytest's autouse mechanism.
+"""
+
+from importlib import import_module
+from pathlib import Path
+
+from winipedia_utils.consts import _DEV_DEPENDENCIES
+from winipedia_utils.git.pre_commit.config import (
+    _pre_commit_config_is_correct,
+)
+from winipedia_utils.modules.module import to_path
+from winipedia_utils.modules.package import (
+    find_packages,
+    get_scr_package,
+    walk_package,
+)
+from winipedia_utils.projects.poetry.config import (
+    _pyproject_tool_configs_are_correct,
+    get_poetry_package_name,
+    laod_pyproject_toml,
+)
+from winipedia_utils.testing.assertions import assert_with_msg
+from winipedia_utils.testing.convention import (
+    TESTS_PACKAGE_NAME,
+    make_test_obj_importpath_from_obj,
+)
+from winipedia_utils.testing.fixtures import autouse_session_fixture
+from winipedia_utils.testing.tests.base.utils.utils import (
+    _conftest_content_is_correct,
+)
+
+
+@autouse_session_fixture
+def _test_dev_dependencies_const_correct() -> None:
+    """Verify that the dev dependencies in consts.py are correct.
+
+    This fixture runs once per test session and checks that the dev dependencies
+    in consts.py are correct by comparing them to the dev dependencies in
+    pyproject.toml.
+
+    Raises:
+        AssertionError: If the dev dependencies in consts.py are not correct
+
+    """
+    if get_poetry_package_name() != "winipedia_utils":
+        # this const is only used in winipedia_utils
+        # to be able to install them with setup.py
+        return
+    toml_dict = laod_pyproject_toml()
+    actual_dev_dependencies = (
+        toml_dict.get("tool", {})
+        .get("poetry", {})
+        .get("group", {})
+        .get("dev", {})
+        .get("dependencies", {})
+        .keys()
+    )
+    assert_with_msg(
+        set(actual_dev_dependencies) == set(_DEV_DEPENDENCIES),
+        "Dev dependencies in consts.py are not correct",
+    )
+
+
+@autouse_session_fixture
+def _test_conftest_exists_and_is_correct() -> None:
+    """Verify that the conftest.py file exists and has the correct content.
+
+    This fixture runs once per test session and checks that the conftest.py file
+    exists in the tests directory and contains the correct pytest_plugins configuration.
+
+    Raises:
+        AssertionError: If the conftest.py file doesn't exist or has incorrect content
+
+    """
+    conftest_path = Path(TESTS_PACKAGE_NAME, "conftest.py")
+    assert_with_msg(
+        conftest_path.is_file(),
+        f"Expected conftest.py file at {conftest_path} but it doesn't exist",
+    )
+
+    assert_with_msg(
+        _conftest_content_is_correct(conftest_path),
+        "conftest.py has incorrect content",
+    )
+
+
+@autouse_session_fixture
+def _test_pyproject_toml_is_correct() -> None:
+    """Verify that the pyproject.toml file exists and has the correct content.
+
+    This fixture runs once per test session and checks that the pyproject.toml file
+    exists in the root directory and contains the correct content.
+
+    Raises:
+        AssertionError: If the pyproject.toml file doesn't exist
+                        or has incorrect content
+
+    """
+    pyproject_toml_path = Path("pyproject.toml")
+    assert_with_msg(
+        pyproject_toml_path.is_file(),
+        f"Expected pyproject.toml file at {pyproject_toml_path} but it doesn't exist",
+    )
+    assert_with_msg(
+        _pyproject_tool_configs_are_correct(),
+        "pyproject.toml has incorrect content.",
+    )
+
+
+@autouse_session_fixture
+def _test_pre_commit_config_yaml_is_correct() -> None:
+    """Verify that the pre-commit yaml is correctly defining winipedia utils hook.
+
+    Checks that the yaml starts with the winipedia utils hook.
+    """
+    pre_commit_config = Path(".pre-commit-config.yaml")
+
+    assert_with_msg(
+        pre_commit_config.is_file(),
+        f"Expected {pre_commit_config} to exist but it doesn't.",
+    )
+    assert_with_msg(
+        _pre_commit_config_is_correct(),
+        "Pre commit config is not correct.",
+    )
+
+
+@autouse_session_fixture
+def _test_no_namespace_packages() -> None:
+    """Verify that there are no namespace packages in the project.
+
+    This fixture runs once per test session and checks that all packages in the
+    project are regular packages with __init__.py files, not namespace packages.
+
+    Raises:
+        AssertionError: If any namespace packages are found
+
+    """
+    packages = find_packages(depth=None)
+    namespace_packages = find_packages(depth=None, include_namespace_packages=True)
+
+    any_namespace_packages = set(namespace_packages) - set(packages)
+    assert_with_msg(
+        not any_namespace_packages,
+        f"Found namespace packages: {any_namespace_packages}. "
+        f"All packages should have __init__.py files.",
+    )
+
+
+@autouse_session_fixture
+def _test_all_src_code_in_one_package() -> None:
+    """Verify that all source code is in a single package.
+
+    This fixture runs once per test session and checks that there is only one
+    source package besides the tests package.
+
+    Raises:
+        AssertionError: If there are multiple source packages
+
+    """
+    packages = find_packages(depth=0)
+    src_package = get_scr_package().__name__
+    expected_packages = {TESTS_PACKAGE_NAME, src_package}
+    assert_with_msg(
+        set(packages) == expected_packages,
+        f"Expected only packages {expected_packages}, but found {packages}",
+    )
+
+
+@autouse_session_fixture
+def _test_project_structure_mirrored() -> None:
+    """Verify that the project structure is mirrored in tests.
+
+    This fixture runs once per test session and checks that for every package and
+    module in the source package, there is a corresponding test package and module.
+
+    Raises:
+        AssertionError: If any package or module doesn't have a corresponding test
+
+    """
+    src_package = get_scr_package()
+
+    # we will now go through all the modules in the src package and check
+    # that there is a corresponding test module
+    for package, modules in walk_package(src_package):
+        test_package_name = make_test_obj_importpath_from_obj(package)
+        test_package = import_module(test_package_name)
+        assert_with_msg(
+            bool(test_package),
+            f"Expected test package {test_package_name} to be a module",
+        )
+
+        for module in modules:
+            test_module_name = make_test_obj_importpath_from_obj(module)
+            test_module = import_module(test_module_name)
+            assert_with_msg(
+                bool(test_module),
+                f"Expected test module {test_module_name} to be a module",
+            )
+
+
+@autouse_session_fixture
+def _test_no_unitest_package_usage() -> None:
+    """Verify that the unittest package is not used in the project.
+
+    This fixture runs once per test session and checks that the unittest package
+    is not used in the project.
+
+    Raises:
+        AssertionError: If the unittest package is used
+
+    """
+    for path in Path().rglob("*.py"):
+        if path == to_path(__name__, is_package=False):
+            continue
+        assert_with_msg(
+            "unittest" not in path.read_text(),
+            f"Found unittest usage in {path}. Use pytest instead.",
+        )

winipedia_utils/testing/tests/base/utils/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.testing.tests.base.utils."""

winipedia_utils/testing/tests/base/utils/utils.py

@@ -0,0 +1,82 @@
+"""Testing utilities for introspection and validation.
+
+This module provides utility functions for working with tests, including:
+- Asserting that all objects in the source have corresponding test objects
+- Generating the content for a conftest.py file
+
+Returns:
+    Various utility functions for testing introspection and validation.
+
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from winipedia_utils.modules.module import get_objs_from_obj, make_obj_importpath
+from winipedia_utils.testing.assertions import assert_with_msg
+from winipedia_utils.testing.convention import (
+    get_obj_from_test_obj,
+    make_test_obj_importpath_from_obj,
+    make_untested_summary_error_msg,
+)
+
+
+def _assert_no_untested_objs(
+    test_obj: ModuleType | type | Callable[..., Any],
+) -> None:
+    """Assert that all objects in the source have corresponding test objects.
+
+    This function verifies that every object (function, class, or method) in the
+    source module or class has a corresponding test object in the test module or class.
+
+    Args:
+        test_obj: The test object (module, class, or function) to check
+
+    Raises:
+        AssertionError: If any object in the source lacks a corresponding test object,
+            with a detailed error message listing the untested objects
+
+    """
+    test_objs = get_objs_from_obj(test_obj)
+    test_objs_paths = {make_obj_importpath(o) for o in test_objs}
+
+    obj = get_obj_from_test_obj(test_obj)
+    objs = get_objs_from_obj(obj)
+    supposed_test_objs_paths = {make_test_obj_importpath_from_obj(o) for o in objs}
+
+    untested_objs = supposed_test_objs_paths - test_objs_paths
+
+    assert_with_msg(not untested_objs, make_untested_summary_error_msg(untested_objs))
+
+
+def _get_conftest_content() -> str:
+    """Get the content for a conftest.py file when using winipedia_utils."""
+    return '''
+"""Pytest configuration for tests.
+
+This module configures pytest plugins for the test suite, setting up the necessary
+fixtures and hooks for the different
+test scopes (function, class, module, package, session).
+It also import custom plugins from tests/base/scopes.
+This file should not be modified manually.
+"""
+
+pytest_plugins = ["winipedia_utils.testing.tests.conftest"]
+'''.strip()
+
+
+def _conftest_content_is_correct(conftest_path: Path) -> bool:
+    """Check if the conftest.py file has the correct content.
+
+    Args:
+        conftest_path: The path to the conftest.py file
+
+    Returns:
+        True if the conftest.py file exists and has the correct content, False otherwise
+
+    """
+    if not conftest_path.exists():
+        return False
+    return conftest_path.read_text().startswith(_get_conftest_content())

winipedia_utils/testing/tests/conftest.py

@@ -0,0 +1,26 @@
+"""Pytest configuration for winipedia_utils tests.
+
+finds all the plugins in the tests directory and the package's testing module
+and adds them to pytest_plugins. This way defining reusable fixtures is easy.
+"""
+
+from winipedia_utils.consts import PACKAGE_NAME
+from winipedia_utils.modules.module import to_module_name, to_path
+
+custom_plugin_path = to_path("tests.base.fixtures", is_package=True)
+package_plugin_path = (
+    to_path(f"{PACKAGE_NAME}.testing", is_package=True) / custom_plugin_path
+)
+
+custom_plugin_module_names = [
+    to_module_name(path) for path in custom_plugin_path.rglob("*.py")
+]
+package_plugin_module_names = [
+    to_module_name(path) for path in package_plugin_path.rglob("*.py")
+]
+
+
+pytest_plugins = [
+    *package_plugin_module_names,
+    *custom_plugin_module_names,
+]

winipedia_utils/text/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.text."""

winipedia_utils/text/string.py

@@ -0,0 +1,126 @@
+"""String manipulation utilities for text processing.
+
+This module provides utility functions for working with strings, including
+input handling, XML parsing, string truncation, and hashing operations.
+These utilities simplify common string manipulation tasks throughout the application.
+"""
+
+import hashlib
+import textwrap
+from io import StringIO
+
+from defusedxml import ElementTree as DefusedElementTree
+
+from winipedia_utils.concurrent.multiprocessing import (
+    cancel_on_timeout,
+)
+from winipedia_utils.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def ask_for_input_with_timeout(prompt: str, timeout: int) -> str:
+    """Request user input with a timeout constraint.
+
+    Args:
+        prompt: The text prompt to display to the user
+        timeout: Maximum time in seconds to wait for input
+
+    Returns:
+        The user's input as a string
+
+    Raises:
+        TimeoutError: If the user doesn't provide input within the timeout period
+
+    """
+
+    @cancel_on_timeout(timeout, "Input not given within the timeout")
+    def give_input() -> str:
+        return input(prompt)
+
+    user_input: str = give_input()
+
+    return user_input
+
+
+def find_xml_namespaces(xml: str | StringIO) -> dict[str, str]:
+    """Extract namespace declarations from XML content.
+
+    Args:
+        xml: XML content as a string or StringIO object
+
+    Returns:
+        Dictionary mapping namespace prefixes to their URIs,
+        excluding the default namespace
+
+    """
+    if not isinstance(xml, StringIO):
+        xml = StringIO(xml)
+    # Extract the namespaces from the root tag
+    namespaces_: dict[str, str] = {}
+    iter_ns = DefusedElementTree.iterparse(xml, events=["start-ns"])
+    for _, elem in iter_ns:
+        prefix, uri = elem
+        namespaces_[prefix] = uri
+
+    namespaces_.pop("", None)
+
+    return namespaces_
+
+
+def value_to_truncated_string(value: object, max_length: int) -> str:
+    """Convert any value to a string and truncate if longer than max_length.
+
+    Args:
+        value: Any object to convert to string
+        max_length: Maximum length of the resulting string
+
+    Returns:
+        Truncated string representation of the value
+
+    """
+    string = str(value)
+    return textwrap.shorten(string, width=max_length, placeholder="...")
+
+
+def get_reusable_hash(value: object) -> str:
+    """Generate a consistent hash for any object.
+
+    Creates a SHA-256 hash of the string representation of the given value.
+    This hash is deterministic and can be used for caching or identification.
+
+    Args:
+        value: Any object to hash
+
+    Returns:
+        Hexadecimal string representation of the SHA-256 hash
+
+    """
+    value_str = str(value)
+    return hashlib.sha256(value_str.encode("utf-8")).hexdigest()
+
+
+def split_on_uppercase(string: str) -> list[str]:
+    """Split a string on uppercase letters.
+
+    Args:
+        string: String to split
+
+    Returns:
+        List of substrings split on uppercase letters
+
+    Example:
+        split_on_uppercase("HelloWorld") -> ["Hello", "World"]
+
+    """
+    letters = list(string)
+    parts = []
+    current_part = ""
+    for letter in letters:
+        if letter.isupper() and current_part:
+            parts.append(current_part)
+            current_part = letter
+        else:
+            current_part += letter
+    parts.append(current_part)
+    return parts

winipedia_utils-0.1.0.dist-info/LICENSE

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