hammad-python 0.0.29__py3-none-any.whl → 0.0.31__py3-none-any.whl

ham/__init__.py

@@ -0,0 +1,10 @@
+"""ham
+
+```markdown
+## `hammad-python`
+
+Fun bunch of stuff ***:)***
+```
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

{hammad_python-0.0.29.dist-info → hammad_python-0.0.31.dist-info}/METADATA

@@ -1,6 +1,7 @@
 Metadata-Version: 2.4
 Name: hammad-python
-Version: 0.0.29
+Version: 0.0.31
+Summary: Personal Python utilities and tools
 Author-email: Hammad Saeed <hammadaidev@gmail.com>
 License: MIT License
         
@@ -25,37 +26,10 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: ddgs>=9.0.0
-Requires-Dist: fasta2a>=0.5.0
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: msgspec>=0.19.0
-Requires-Dist: nest-asyncio>=1.6.0
-Requires-Dist: pydantic>=2.11.7
-Requires-Dist: rich>=14.0.0
-Requires-Dist: selectolax>=0.3.31
-Requires-Dist: sqlalchemy>=2.0.41
-Requires-Dist: tantivy>=0.24.0
-Requires-Dist: tenacity>=8.2.3
-Requires-Dist: typing-inspect>=0.9.0
-Provides-Extra: ai
-Requires-Dist: instructor>=1.9.0; extra == 'ai'
-Requires-Dist: litellm>=1.73.6; extra == 'ai'
-Requires-Dist: qdrant-client>=1.14.3; extra == 'ai'
-Provides-Extra: genai
-Requires-Dist: fastapi>=0.115.6; extra == 'genai'
-Requires-Dist: instructor>=1.9.0; extra == 'genai'
-Requires-Dist: litellm>=1.73.6; extra == 'genai'
-Requires-Dist: mcp>=1.10.1; extra == 'genai'
-Requires-Dist: pydantic-graph>=0.4.2; extra == 'genai'
-Requires-Dist: qdrant-client>=1.14.3; extra == 'genai'
-Requires-Dist: uvicorn>=0.34.0; extra == 'genai'
-Provides-Extra: graph
-Requires-Dist: pydantic-graph>=0.4.2; extra == 'graph'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.10.1; extra == 'mcp'
-Provides-Extra: serve
-Requires-Dist: fastapi>=0.115.6; extra == 'serve'
-Requires-Dist: uvicorn>=0.34.0; extra == 'serve'
+Requires-Dist: hammad-python-core>=0.0.1
+Requires-Dist: hammad-python-data>=0.0.1
+Requires-Dist: hammad-python-genai>=0.0.1
+Requires-Dist: hammad-python-http>=0.0.1
 Description-Content-Type: text/markdown
 
 ## hammad-python

hammad_python-0.0.31.dist-info/RECORD

@@ -0,0 +1,6 @@
+ham/__init__.py,sha256=MA_bJzOy-7HH-wzIPpMiWFlDq_6MwvRFtRinBFdHJ0Y,142
+ham/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hammad_python-0.0.31.dist-info/METADATA,sha256=IfpcOHTQGdS5OddkPu0V9MKX6646xdKJHDY0iQ3NQfc,5454
+hammad_python-0.0.31.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hammad_python-0.0.31.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
+hammad_python-0.0.31.dist-info/RECORD,,

hammad/__init__.py

@@ -1,84 +0,0 @@
-"""hammad-python
-
-A vast ecosystem of ('nightly', dont trust literally any interface to stay the same
-for more than a few days) resources, utilities and components for building applications
-in Python."""
-
-from typing import TYPE_CHECKING
-from ._internal import create_getattr_importer as __hammad_importer__
-
-
-if TYPE_CHECKING:
-    from . import types
-
-    # 'builtins'
-    from .cache import cached
-    from .cli import print, input, animate
-    from .genai import (
-        BaseGraph,
-        plugin,
-        action,
-        select,
-        agent_decorator as agent,
-        language_model_decorator as llm,
-        run_embedding_model as embedding,
-        define_tool as tool,
-    )
-    from .data.collections import create_collection as collection
-    from .formatting.text import convert_to_text as markdown
-    from .mcp import launch_mcp_servers
-    from .logging import create_logger as logger
-    from .service import serve, serve_mcp
-    from .web import (
-        run_web_search as web_search,
-        run_web_request as web_request,
-    )
-
-    from ._main import (
-        to,
-        run,
-        fn,
-        new,
-        read,
-        settings,
-    )
-
-
-__all__ = (
-    # types
-    "types",
-    # -- 'builtins'
-    "cached",
-    "print",
-    "animate",
-    "input",
-    "llm",
-    "agent",
-    "embedding",
-    "tool",
-    "markdown",
-    "launch_mcp_servers",
-    "action",
-    "plugin",
-    "select",
-    "BaseGraph",
-    "collection",
-    "logger",
-    "serve",
-    "serve_mcp",
-    "web_search",
-    "web_request",
-    "to",
-    "run",
-    "fn",
-    "new",
-    "read",
-    "settings",
-)
-
-
-__getattr__ = __hammad_importer__(__all__)
-
-
-def __dir__() -> list[str]:
-    return list(__all__)

hammad/_internal.py

@@ -1,256 +0,0 @@
-"""hammad._internal
-
-Internal utilities"""
-
-from typing import Any, Callable, List, Tuple, Union
-import inspect
-import ast
-import hashlib
-
-# pretty
-from rich.traceback import install
-
-install()
-
-__all__ = ("create_getattr_importer",)
-
-
-class GetAttrImporterError(Exception):
-    """An error that occurs when the `create_getattr_importer` function
-    fails to create a lazy loader function."""
-
-
-class GetAttrImporterCache:
-    """Minimal cache implementation for internal use only
-    within the `create_getattr_importer` function."""
-
-    def __init__(self, maxsize: int = 128):
-        self.maxsize = maxsize
-        self._cache: dict[str, Any] = {}
-
-    def _make_key(self, data: str) -> str:
-        """Create a simple hash key from string data."""
-        return hashlib.sha256(data.encode("utf-8")).hexdigest()[:16]
-
-    def get(self, key: str, default: Any = None) -> Any:
-        """Get value from cache."""
-        return self._cache.get(key, default)
-
-    def set(self, key: str, value: Any) -> None:
-        """Set value in cache with basic LRU eviction."""
-        if len(self._cache) >= self.maxsize and key not in self._cache:
-            # Simple eviction: remove oldest (first) item
-            oldest_key = next(iter(self._cache))
-            del self._cache[oldest_key]
-        self._cache[key] = value
-
-    def cached_call(self, func: Callable[[str], Any]) -> Callable[[str], Any]:
-        """Decorator to cache function calls."""
-
-        def wrapper(arg: str) -> Any:
-            key = self._make_key(arg)
-            result = self.get(key)
-            if result is None:
-                result = func(arg)
-                self.set(key, result)
-            return result
-
-        return wrapper
-
-
-# NOTE:
-# SINGLETON
-GETATTR_IMPORTER_PARSE_CACHE = GetAttrImporterCache(maxsize=64)
-"""Library-wide singleton instance providing caching for the 
-`_parse_type_checking_imports` function."""
-
-
-GETATTR_IMPORTER_TYPE_CHECKING_CACHE = {}
-"""Cache for the `_parse_type_checking_imports` function."""
-
-
-def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]:
-    """Parses the TYPE_CHECKING imports from a source code file, to create
-    a dictionary of local names to (module_path, original_name) tuples.
-
-    This is used to create the mapping used within the `_create_getattr_importer_from_import_dict`
-    function.
-
-    Args:
-        source_code : The source code to parse
-
-    Returns:
-        A dictionary mapping local names to (module_path, original_name) tuples
-    """
-
-    @GETATTR_IMPORTER_PARSE_CACHE.cached_call
-    def _exec(source_code: str) -> dict[str, tuple[str, str]]:
-        tree = ast.parse(source_code)
-        imports = {}
-
-        # Walk through the AST and find TYPE_CHECKING blocks
-        for node in ast.walk(tree):
-            if isinstance(node, ast.If):
-                # Check if this is a TYPE_CHECKING block
-                is_type_checking = False
-
-                if isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING":
-                    is_type_checking = True
-                elif isinstance(node.test, ast.Attribute):
-                    if (
-                        isinstance(node.test.value, ast.Name)
-                        and node.test.value.id == "typing"
-                        and node.test.attr == "TYPE_CHECKING"
-                    ):
-                        is_type_checking = True
-
-                if is_type_checking:
-                    # Process imports in this block
-                    for stmt in node.body:
-                        if isinstance(stmt, ast.ImportFrom) and stmt.module:
-                            # Only add '.' prefix for relative imports
-                            # If stmt.level > 0, it's already a relative import
-                            # If stmt.level == 0 and module doesn't start with '.', it's absolute
-                            if stmt.level > 0:
-                                # Already relative import
-                                module_path = "." * stmt.level + (stmt.module or "")
-                            elif stmt.module.startswith("."):
-                                # Explicit relative import
-                                module_path = stmt.module
-                            elif any(
-                                stmt.module.startswith(name)
-                                for name in ["litellm", "openai", "instructor", "httpx"]
-                            ):
-                                # Known absolute third-party imports
-                                module_path = stmt.module
-                            else:
-                                # Default to relative import for internal modules
-                                module_path = f".{stmt.module}"
-
-                            for alias in stmt.names:
-                                original_name = alias.name
-                                local_name = alias.asname or original_name
-                                imports[local_name] = (module_path, original_name)
-
-        return imports
-
-    return _exec(source_code)
-
-
-def _create_getattr_importer_from_import_dict(
-    imports_dict: dict[str, tuple[str, str]],
-    package: str,
-    all_attrs: Union[Tuple[str, ...], List[str]],
-) -> Callable[[str], Any]:
-    """Creates a lazy loader function for the `__getattr__` method
-    within `__init__.py` modules in Python packages.
-
-    Args:
-        imports_dict : Dictionary mapping attribute names to (module_path, original_name) tuples
-        package : The package name for import_module
-        all_attrs : List of all valid attributes for this module
-
-    Returns:
-        A __getattr__ function that lazily imports modules
-    """
-    from importlib import import_module
-
-    cache = {}
-
-    def __getattr__(name: str) -> Any:
-        if name in cache:
-            return cache[name]
-
-        if name in imports_dict:
-            module_path, original_name = imports_dict[name]
-            module = import_module(module_path, package)
-            result = getattr(module, original_name)
-            cache[name] = result
-            return result
-
-        # Try to import as a submodule
-        try:
-            module_path = f".{name}"
-            module = import_module(module_path, package)
-            cache[name] = module
-            return module
-        except ImportError:
-            pass
-
-        raise GetAttrImporterError(f"module '{package}' has no attribute '{name}'")
-
-    return __getattr__
-
-
-def create_getattr_importer(
-    all: Union[Tuple[str, ...], List[str]],
-) -> Callable[[str], Any]:
-    """Loader used internally within the `hammad` package to create lazy
-    loaders within `__init__.py` modules using the `TYPE_CHECKING` and
-    `all` source code within files.
-
-    This function is meant to be set as the `__getattr__` method / var
-    within modules to allow for direct lazy loading of attributes.
-
-    Example:
-
-        ```
-        # Create a module that contains some imports and TYPE_CHECKING
-        from typing import TYPE_CHECKING
-        from hammad.performance.imports import create_getattr_importer
-
-        if TYPE_CHECKING:
-            from functools import wraps
-
-        all = ("wraps")
-
-        __getattr__ = create_getattr_importer(all)
-
-        # Now, when you import this module, the `wraps` attribute will be
-        # lazily loaded when it is first accessed.
-        ```
-
-    Args:
-        all : The `all` tuple from the calling module
-
-    Returns:
-        A __getattr__ function that lazily imports modules
-    """
-    # Get the calling module's frame
-    frame = inspect.currentframe()
-    if frame is None or frame.f_back is None:
-        raise RuntimeError("Cannot determine calling module")
-
-    calling_frame = frame.f_back
-    module_name = calling_frame.f_globals.get("__name__", "")
-    package = calling_frame.f_globals.get("__package__", "")
-    filename = calling_frame.f_globals.get("__file__", "")
-
-    # Check cache first
-    cache_key = (filename, tuple(all))
-    if cache_key in GETATTR_IMPORTER_TYPE_CHECKING_CACHE:
-        return GETATTR_IMPORTER_TYPE_CHECKING_CACHE[cache_key]
-
-    # Read the source file
-    try:
-        with open(filename, "r") as f:
-            source_code = f.read()
-    except (IOError, OSError):
-        # Fallback: try to get source from the module
-        import sys
-
-        module = sys.modules.get(module_name)
-        if module:
-            source_code = inspect.getsource(module)
-        else:
-            raise RuntimeError(f"Cannot read source for module {module_name}")
-
-    # Parse the source to extract TYPE_CHECKING imports
-    imports_map = _parse_type_checking_imports(source_code)
-
-    # Filter to only include exports that are in __all__
-    filtered_map = {name: path for name, path in imports_map.items() if name in all}
-
-    loader = _create_getattr_importer_from_import_dict(filtered_map, package, all)
-    GETATTR_IMPORTER_TYPE_CHECKING_CACHE[cache_key] = loader
-    return loader

hammad/_main.py

@@ -1,226 +0,0 @@
-"""hammad._main"""
-
-
-class to:
-    """Namespace for converters that can be used to convert objects to various formats.
-
-    The `to` class provides a collection of converters that can be used to convert objects
-    to various formats, such as pydantic models, text, markdown, json, and more.
-    """
-
-    # ! CONVERTERS
-    from .data import (
-        convert_to_pydantic_field as pydantic_field,
-        convert_to_pydantic_model as pydantic_model,
-    )
-    from .data.types import (
-        convert_to_base_text as text,
-        convert_to_simple_text as simple_text,
-        convert_to_code_section as code_section,
-        convert_to_schema_section as schema_section,
-        convert_to_output_instructions as output_instructions,
-    )
-    from .formatting.json import (
-        convert_to_json_schema as json_schema,
-    )
-    from .formatting.text import (
-        convert_to_text as markdown,
-    )
-
-
-class fn:
-    """Namespace for decorators that can be used to modify functions, methods, and classes.
-
-    The `fn` class provides a collection of decorators that can be used to modify functions,
-    methods, and classes in various ways, such as caching results, tracing function calls,
-    and validating input parameters.
-    """
-
-    # ! DECORATORS
-    from .cache import cached, auto_cached
-    from .logging import trace, trace_cls, trace_function, trace_http
-    from .data.models import validator
-    from .runtime import (
-        sequentialize_function as sequentialize,
-        parallelize_function as parallelize,
-        run_with_retry as retry,
-    )
-    from .service import serve, serve_mcp
-
-
-class new:
-    """Namespace for factory functions that create new objects, models, services, and clients.
-
-    The `new` class provides convenient access to a variety of factory functions for creating
-    commonly used objects in the hammad ecosystem, such as caches, collections, databases,
-    models, loggers, agents, services, and web clients.
-
-    Example usage:
-        cache = new.cache(...)
-        collection = new.collection(...)
-        model = new.model(...)
-        logger = new.logger(...)
-        agent = new.agent(...)
-        service = new.service(...)
-        http_client = new.http_client(...)
-    """
-
-    # ! FACTORIES
-    from .cache import (
-        create_cache as cache,
-    )
-    from .data import (
-        create_collection as collection,
-        create_database as database,
-        create_model as model,
-    )
-    from .logging import create_logger as logger
-    from .genai import (
-        create_agent as agent,
-        create_embedding_model as embedding_model,
-        create_language_model as language_model,
-    )
-    from .service import (
-        create_service as service,
-        async_create_service as async_service,
-    )
-    from .mcp import (
-        MCPClient as mcp_client,
-    )
-    from .web import (
-        create_http_client as http_client,
-        create_openapi_client as openapi_client,
-        create_search_client as search_client,
-    )
-
-
-class run:
-    """Centeral namespace for 'one-off' runners, or functions that can be
-    executed directly, and standalone."""
-
-    # ! RUNNERS
-    from .genai import (
-        run_agent as agent,
-        run_agent_iter as agent_iter,
-        run_embedding_model as embedding_model,
-        run_image_edit_model as image_edit_model,
-        run_image_generation_model as image_generation_model,
-        run_image_variation_model as image_variation_model,
-        run_language_model as language_model,
-        run_reranking_model as reranking_model,
-        run_transcription_model as transcription_model,
-        run_tts_model as text_to_speech_model,
-    )
-    from .mcp import (
-        launch_mcp_servers as mcp_servers,
-    )
-    from .web import (
-        run_news_search as news_search,
-        run_web_search as web_search,
-        run_web_request as web_request,
-    )
-
-
-class read:
-    """Namespace for various resource, URL or other file-type readers."""
-
-    from .data.configurations import (
-        read_configuration_from_dotenv as configuration_from_dotenv,
-        read_configuration_from_file as configuration_from_file,
-        read_configuration_from_url as configuration_from_url,
-        read_configuration_from_os_prefix as configuration_from_os_prefix,
-        read_configuration_from_os_vars as configuration_from_os_vars,
-    )
-    from .data.types import (
-        read_file_from_bytes as file_from_bytes,
-        read_file_from_path as file_from_path,
-        read_file_from_url as file_from_url,
-        read_audio_from_path as audio_from_path,
-        read_audio_from_url as audio_from_url,
-        read_image_from_path as image_from_path,
-        read_image_from_url as image_from_url,
-    )
-    from .web import (
-        read_web_page as web_page,
-        read_web_pages as web_pages,
-        extract_web_page_links as extract_links,
-    )
-
-
-class settings:
-    """Namespace class for all settings definitions within the ecosystem. This is an
-    easy way to find the configuration settings for the component you are intending
-    to use."""
-
-    # NOTE:
-    # these are attached to the 'core/builtin' extensions imported at the very top
-    # hence the weird very very literal names
-    from .cli import (
-        CLIStyleLiveSettings as live,
-        CLIStyleBackgroundSettings as bg,
-        CLIStyleRenderableSettings as style,
-    )
-
-    from .data import (
-        QdrantCollectionIndexSettings as qdrant,
-        QdrantCollectionIndexQuerySettings as qdrant_query,
-        TantivyCollectionIndexSettings as tantivy,
-        TantivyCollectionIndexQuerySettings as tantivy_query,
-    )
-    from .logging.logger import LoggerLevelSettings as logger_level
-    from .genai import (
-        AgentSettings as agent,
-        LanguageModelSettings as language_model,
-        EmbeddingModelSettings as embedding_model,
-    )
-    from .mcp import (
-        MCPClientSseSettings as mcp_client_sse,
-        MCPClientStdioSettings as mcp_client_stdio,
-        MCPClientStreamableHttpSettings as mcp_client_streamable_http,
-        MCPServerSseSettings as mcp_server_sse,
-        MCPServerStdioSettings as mcp_server_stdio,
-        MCPServerStreamableHttpSettings as mcp_server_streamable_http,
-    )
-
-
-__all__ = (
-    # hammad.cache
-    "cached",
-    # hammad.cli
-    "print",
-    "input",
-    "animate",
-    # hammad.logging
-    "logger",
-    # hammad.genai
-    "BaseGraph",
-    "plugin",
-    "action",
-    "agent",
-    "llm",
-    "tool",
-    # hammad.data.collections
-    "collection",
-    # hammad.formatting.text
-    "markdown",
-    # hammad.mcp
-    "launch_mcp_servers",
-    # hammad.service
-    "serve",
-    "serve_mcp",
-    # hammad.web
-    "web_search",
-    "web_request",
-    # hammad.to
-    "to",
-    # hammad.fn
-    "fn",
-    # hammad.new
-    "new",
-    # hammad.run
-    "run",
-    # hammad.read
-    "read",
-    # hammad.settings
-    "settings",
-)

hammad/cache/__init__.py

@@ -1,40 +0,0 @@
-"""hammad.cache"""
-
-from typing import TYPE_CHECKING
-from .._internal import create_getattr_importer
-
-
-if TYPE_CHECKING:
-    from .base_cache import BaseCache, CacheParams, CacheReturn, CacheType
-    from .file_cache import FileCache, FileCacheLocation
-    from .ttl_cache import TTLCache
-    from .cache import Cache, create_cache
-    from .decorators import cached, auto_cached, clear_decorator_cache
-
-
-__all__ = (
-    # hammad.performance.cache.base_cache
-    "BaseCache",
-    "CacheParams",
-    "CacheReturn",
-    "CacheType",
-    # hammad.performance.cache.file_cache
-    "FileCache",
-    "FileCacheLocation",
-    # hammad.performance.cache.ttl_cache
-    "TTLCache",
-    # hammad.performance.cache.cache
-    "Cache",
-    "create_cache",
-    # hammad.performance.cache.decorators
-    "cached",
-    "auto_cached",
-    "clear_decorator_cache",
-)
-
-
-__getattr__ = create_getattr_importer(__all__)
-
-
-def __dir__() -> list[str]:
-    return sorted(__all__)