hammad-python 0.0.30__py3-none-any.whl → 0.0.32__py3-none-any.whl

ham/__init__.py

@@ -0,0 +1,200 @@
+"""ham
+
+```markdown
+## `hammad-python`
+
+Fun bunch of stuff ***:)***
+
+This module is a collection over various sub-packages that
+define the `ham` namespace. These packages include:
+
+- `hammad-python-core`
+- `hammad-python-data`
+- `hammad-python-genai`
+- `hammad-python-http`
+```
+
+You can access a variety of the primary resources from these modules
+directly from this top level module.
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from typing import TYPE_CHECKING
+
+try:
+    from ham.core._internal import type_checking_importer
+except ImportError:
+    from .core._internal import type_checking_importer  # type: ignore
+
+
+if TYPE_CHECKING:
+    try:
+        # ham.core
+        from ham.core._internal._logging import set_debug, set_verbose
+        from ham.core.cache import cached, auto_cached
+        from ham.core.cli import print, animate, input, log, log_iterable, log_progress
+        from ham.core.conversion import (
+            convert_to_text,
+            convert_to_json_schema,
+            convert_to_model,
+            convert_to_pydantic_model,
+        )
+        from ham.core.logging import get_logger, trace, trace_http
+
+        # ham.data
+        from ham.data.collections import (
+            create_collection,
+        )
+
+        # ham.genai
+        from ham.genai.models.embeddings import run_embedding_model
+        from ham.genai.models.language import run_language_model
+        from ham.genai.models.reranking import run_reranking_model
+        from ham.genai.models.multimodal import (
+            run_image_generation_model,
+            run_transcription_model,
+            run_tts_model,
+        )
+        from ham.genai.agents import create_agent, run_agent, run_agent_iter
+        from ham.genai.graphs import (
+            # NOTE: lol... uh i just really wanted everything to be lowercase..
+            # this may need a once over
+            BaseGraph as basegraph,
+            action as graphaction,
+        )
+        from ham.genai.prompted import (
+            prompted_fn as prompted,
+            contextualize,
+            itemize,
+            select,
+            tool,
+        )
+        from ham.genai.a2a import as_a2a_app
+
+        # ham.http
+        from ham.http import (
+            create_client,
+            create_openapi_client,
+            create_http_client,
+            create_mcp_client,
+            create_server,
+            create_fast_service,
+            function_server,
+            function_mcp_server,
+            run_web_request,
+            read_web_page,
+            read_web_pages,
+            run_web_search,
+            run_news_search,
+            extract_web_page_links,
+            create_search_client,
+        )
+    except ImportError:
+        from ham.core._internal import (  # type: ignore
+            set_debug,
+            set_verbose,
+        )
+        from ham.data import (  # type: ignore
+            create_collection,
+        )
+        from ham.genai import (  # type: ignore
+            create_agent,
+            run_agent,
+            run_agent_iter,
+            run_embedding_model,
+            run_language_model,
+            run_reranking_model,
+            run_image_generation_model,
+            run_transcription_model,
+            run_tts_model,
+            basegraph,
+            graphaction,
+            prompted,
+            contextualize,
+            itemize,
+            select,
+            tool,
+        )
+        from ham.http import (  # type: ignore
+            create_client,
+            create_openapi_client,
+            create_http_client,
+            create_mcp_client,
+            create_server,
+            create_fast_service,
+            function_server,
+            function_mcp_server,
+            run_web_request,
+            read_web_page,
+            read_web_pages,
+            run_web_search,
+            run_news_search,
+            extract_web_page_links,
+            create_search_client,
+        )
+
+
+__all__ = (
+    # ham.core
+    "set_debug",
+    "set_verbose",
+    "cached",
+    "auto_cached",
+    "print",
+    "animate",
+    "input",
+    "log",
+    "log_iterable",
+    "log_progress",
+    "convert_to_text",
+    "convert_to_json_schema",
+    "convert_to_model",
+    "convert_to_pydantic_model",
+    "get_logger",
+    "trace",
+    "trace_http",
+    # ham.data
+    "create_collection",
+    # ham.genai
+    "create_agent",
+    "run_agent",
+    "run_agent_iter",
+    "run_embedding_model",
+    "run_language_model",
+    "run_reranking_model",
+    "run_image_generation_model",
+    "run_transcription_model",
+    "run_tts_model",
+    "basegraph",
+    "graphaction",
+    "prompted",
+    "contextualize",
+    "itemize",
+    "select",
+    "tool",
+    # ham.http
+    "create_client",
+    "create_openapi_client",
+    "create_http_client",
+    "create_mcp_client",
+    "create_server",
+    "create_fast_service",
+    "function_server",
+    "function_mcp_server",
+    "run_web_request",
+    "read_web_page",
+    "read_web_pages",
+    "run_web_search",
+    "run_news_search",
+    "extract_web_page_links",
+    "create_search_client",
+)
+
+
+__getattr__ = type_checking_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    """Get the attributes of the hammad module."""
+    return __all__

{hammad_python-0.0.30.dist-info → hammad_python-0.0.32.dist-info}/METADATA

@@ -1,6 +1,7 @@
 Metadata-Version: 2.4
 Name: hammad-python
-Version: 0.0.30
+Version: 0.0.32
+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.2
+Requires-Dist: hammad-python-data>=0.0.2
+Requires-Dist: hammad-python-genai>=0.0.2
+Requires-Dist: hammad-python-http>=0.0.2
 Description-Content-Type: text/markdown
 
 ## hammad-python

hammad_python-0.0.32.dist-info/RECORD

@@ -0,0 +1,6 @@
+ham/__init__.py,sha256=J1ye-mmybVCdFvMaYJjYVNJa7CEME4W6bIzLuGsQvKE,5215
+ham/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hammad_python-0.0.32.dist-info/METADATA,sha256=Nn4_482LfJu6FYy39l6SW0qkTTHKqK_rrizDS7SxhY0,5454
+hammad_python-0.0.32.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hammad_python-0.0.32.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
+hammad_python-0.0.32.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