hammad-python 0.0.13__py3-none-any.whl → 0.0.15__py3-none-any.whl

hammad_python-0.0.15.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: hammad-python
+Version: 0.0.15
+Author-email: Hammad Saeed <hammadaidev@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Hammad Saeed
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: ddgs>=9.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: msgspec>=0.19.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>=9.1.2
+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: 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'
+Description-Content-Type: text/markdown
+
+## hammad-python
+
+> __Happily Accelerated Micro-Modules (_for_) Application Development__
+
+## Introduction
+
+The `hammad-python` library, is a mix of a love letter and collection of mixed resources for
+developing Python applications. This library is meant to be used for rapid prototyping and
+development, and is focused on providing styled placeholder tools for common patterns, tasks
+and workflows.
+
+The package is currently built into the following structures:
+
+- `hammad-python` : Contains most core functionality and resources.
+- `hammad-python[ai]` : Contains easy to use resources for Generative AI related tasks such as
+   generating completions with language models, or creating embeddings.
+- `hammad-python[serve]` : Contains FastAPI / Uvicorn based resources for serving and running applications.
+
+## Installation
+
+You can install the package using `pip` or `uv`:
+
+```bash
+pip install hammad-python
+
+# or install the `ai` extension
+# pip install 'hammad-python[ai]'
+
+# or install the `serve` extension
+# pip install 'hammad-python[serve]'
+```
+
+```bash
+uv pip install hammad-python
+
+# or install the `ai` extension
+# uv pip install 'hammad-python[ai]'
+
+# or install the `serve` extension
+# uv pip install 'hammad-python[serve]'
+```
+
+## Basic Usage
+
+### Data Structures, Databases and Other Data Related Resources
+
+#### Collections
+
+Using `hammad.data.collections` is a simple way to create searchable collections of
+data using both `bm25` and `vector` based search.
+
+```python
+from hammad.data.collections import create_collection
+
+# Create either a `vector` or `searchable` collection
+col = create_collection(type = "searchable")
+
+# add anything to the collection
+col.add("This is some text")
+col.add(5)
+col.add({'text' : "this is a dictionary"})
+
+# search the collection
+print(col.query("text"))
+```
+
+#### Databases
+
+Any collection can be either used as a standalone database, or can be added as one
+of the collections within a database. Databases provide a unified interface for handling
+both `Searchable` and `Vector` based collections.
+
+```python
+from hammad.data.collections import create_collection
+from hammad.data.databases import Database
+
+# Create either a `vector` or `searchable` collection
+col = create_collection(type = "searchable")
+
+col.add("This is some text")
+
+# Databases can either be created on memory or using a path
+db = Database(location = "memory")
+
+db.add_collection(col)
+
+# search globally or within a single collection
+print(db.query("text"))
+```
+
+### Styling / Introspection Resources
+
+The `hammad-python` package contains a variety of components that can be used
+to easily style, or run introspection (logging) on your code.
+
+```python
+from hammad.cli import print, input, animate
+
+# Use extended `rich` styling easily
+print("Hello, World", bg_settings = {"title" : "This is a title"})
+
+# Easily collect various forms of input in a single function
+class User(BaseModel):
+    name : str
+    age : int
+
+# TIP:
+# you can style this the same way with `print`
+user = input("Enter some information about yourself: ", schema = User)
+
+# easily run a collection of prebuilt animations
+animate("This is a rainbow!", type = "rainbow", duration = 2, refresh_rate = 20)
+```
+
+Using the various `hammad.logging` resources, you can both create custom & styled
+loggers, as well as easily inspect various aspects of your code during runtime.
+
+```python
+from hammad.logging import Logger
+
+# create standard / file based loggers easily
+logger = Logger("hammad", level = "info", rich = Trues)
+
+file_logger = Logger("hammad-file", level = "info", file = "hammad.log")
+
+# log to the console
+logger.info("This is an info message")
+
+# Use the various `trace_` methods to run various introspection tasks
+from hammad.logging import (
+   trace,
+   trace_cls,
+   trace_function,
+   trace_http
+)
+```

hammad_python-0.0.15.dist-info/RECORD

@@ -0,0 +1,4 @@
+hammad_python-0.0.15.dist-info/METADATA,sha256=76e_P5ZnWxhhfnyhA0B91cnlFtAxepwavtFancGsUuw,5907
+hammad_python-0.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hammad_python-0.0.15.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
+hammad_python-0.0.15.dist-info/RECORD,,

hammad/__init__.py

@@ -1,180 +0,0 @@
-"""hammad-python
-
-```markdown
-## Happliy Accelerated Micro Modules (for) Application Development
-```
-"""
-
-from typing import TYPE_CHECKING
-from ._core._utils._import_utils import _auto_create_getattr_loader
-
-
-if TYPE_CHECKING:
-    # hammad.ai
-    # NOTE:
-    # TO USE MODULES FROM THE `hammad.ai` EXTENSION,
-    # REQUIRES INSTALLATION OF THE `hammad-python[ai]` PACKAGE.
-    from .ai import (
-        create_completion,
-        async_create_completion,
-        create_embeddings,
-        async_create_embeddings,
-    )
-
-    # hammad.base
-    from .base import Model, field, create_model, is_field, is_model, validator
-
-    # hammad.cache
-    from .cache import Cache, cached, auto_cached, create_cache
-
-    # hammad.cli
-    from .cli import print, animate, input
-
-    # hammad.configuration
-    from .configuration import (
-        Configuration,
-        read_configuration_from_os_vars,
-        read_configuration_from_dotenv,
-        read_configuration_from_file,
-        read_configuration_from_url,
-        read_configuration_from_os_prefix,
-    )
-
-    # hammad.data
-    from .data import Collection, Database, create_collection, create_database
-
-    # hammad.json
-    from .json import encode_json, decode_json, convert_to_json_schema
-
-    # hammad.logging
-    from .logging import (
-        Logger,
-        create_logger,
-        trace,
-        trace_cls,
-        trace_function,
-        trace_http,
-        install_trace_http,
-    )
-
-    # hammad.multithreading
-    from .multithreading import (
-        run_parallel,
-        run_sequentially,
-        run_with_retry,
-        retry,
-    )
-
-    # hammad.pydantic
-    from .pydantic import (
-        convert_to_pydantic_field,
-        convert_to_pydantic_model,
-    )
-
-    # hammad.text
-    from .text import (
-        Text,
-        OutputText,
-        SimpleText,
-        convert_to_text,
-        convert_type_to_text,
-        convert_docstring_to_text,
-    )
-
-    # hammad.web
-    from .web import (
-        create_http_client,
-        create_openapi_client,
-        create_search_client,
-        search_news,
-        search_web,
-        run_web_request,
-        read_web_page,
-        read_web_pages,
-        extract_page_links,
-    )
-
-    # hammad.yaml
-    from .yaml import encode_yaml, decode_yaml, read_yaml_file
-
-
-__all__ = (
-    # hammad.ai
-    "create_completion",
-    "async_create_completion",
-    "create_embeddings",
-    "async_create_embeddings",
-    # hammad.base
-    "Model",
-    "field",
-    "create_model",
-    # hammad.cache
-    "Cache",
-    "cached",
-    "auto_cached",
-    "create_cache",
-    # hammad.cli
-    "print",
-    "animate",
-    "input",
-    # hammad.configuration
-    "Configuration",
-    "read_configuration_from_os_vars",
-    "read_configuration_from_dotenv",
-    "read_configuration_from_file",
-    "read_configuration_from_url",
-    "read_configuration_from_os_prefix",
-    # hammad.data
-    "Collection",
-    "Database",
-    "create_collection",
-    "create_database",
-    # hammad.json
-    "encode_json",
-    "decode_json",
-    "convert_to_json_schema",
-    # hammad.logging
-    "Logger",
-    "create_logger",
-    "trace",
-    "trace_cls",
-    "trace_function",
-    "trace_http",
-    "install_trace_http",
-    # hammad.multithreading
-    "run_parallel",
-    "run_sequentially",
-    "run_with_retry",
-    "retry",
-    # hammad.pydantic
-    "convert_to_pydantic_field",
-    "convert_to_pydantic_model",
-    # hammad.text
-    "Text",
-    "OutputText",
-    "SimpleText",
-    "convert_to_text",
-    "convert_type_to_text",
-    "convert_docstring_to_text",
-    # hammad.web
-    "create_http_client",
-    "create_openapi_client",
-    "create_search_client",
-    "search_news",
-    "search_web",
-    "run_web_request",
-    "read_web_page",
-    "read_web_pages",
-    "extract_page_links",
-    # hammad.yaml
-    "encode_yaml",
-    "decode_yaml",
-    "read_yaml_file",
-)
-
-
-__getattr__ = _auto_create_getattr_loader(__all__)
-
-
-def __dir__() -> list[str]:
-    return list(__all__)

hammad/_core/__init__.py

@@ -1 +0,0 @@
-"""hammad._core"""

hammad/_core/_utils/__init__.py

@@ -1,4 +0,0 @@
-"""hammad._core._utils
-
-Contains internal utility functions use at a low level for various cases
-throughout the `hammad` package."""

hammad/_core/_utils/_import_utils.py

@@ -1,182 +0,0 @@
-"""hammad._core._utils._import_utils"""
-
-from typing import Any, Callable
-import inspect
-import ast
-import hashlib
-
-__all__ = ("_auto_create_getattr_loader",)
-
-
-class _ModuleCache:
-    """Minimal cache implementation for internal use only."""
-
-    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
-
-
-# Global cache instance for parse function
-_parse_cache = _ModuleCache(maxsize=64)
-
-
-def _create_getattr_loader(
-    imports_dict: dict[str, tuple[str, str]], package: str
-) -> Callable[[str], Any]:
-    """Create a lazy loader function for __getattr__.
-
-    Args:
-        imports_dict: Dictionary mapping attribute names to (module_path, original_name) tuples
-        package: The package name for import_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
-        raise AttributeError(f"module '{package}' has no attribute '{name}'")
-
-    return __getattr__
-
-
-_type_checking_cache = {}
-
-
-def _auto_create_getattr_loader(all_exports: tuple[str, ...]) -> Callable[[str], Any]:
-    """Automatically create a lazy loader by inspecting the calling module.
-
-    This function inspects the calling module's source code to extract
-    TYPE_CHECKING imports and automatically builds the import map.
-
-    Args:
-        all_exports: 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_exports))
-    if cache_key in _type_checking_cache:
-        return _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_exports
-    }
-
-    loader = _create_getattr_loader(filtered_map, package)
-    _type_checking_cache[cache_key] = loader
-    return loader
-
-
-def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]:
-    """Parse TYPE_CHECKING imports from source code to build import map.
-
-    Args:
-        source_code: The source code containing TYPE_CHECKING imports
-
-    Returns:
-        Dictionary mapping local names to (module_path, original_name) tuples
-    """
-
-    @_parse_cache.cached_call
-    def _exec(source_code: str) -> dict[str, tuple[str, str]]:
-        tree = ast.parse(source_code)
-        imports = {}
-
-        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:
-                            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)

hammad/ai/__init__.py

@@ -1,59 +0,0 @@
-"""hammad.ai"""
-
-from typing import TYPE_CHECKING
-from .._core._utils._import_utils import _auto_create_getattr_loader
-
-if TYPE_CHECKING:
-    from .completions import (
-        CompletionsClient,
-        Completion,
-        CompletionChunk,
-        CompletionsInputParam,
-        CompletionsModelName,
-        CompletionsOutputType,
-        CompletionStream,
-        AsyncCompletionStream,
-        async_create_completion,
-        create_completion,
-    )
-    from .embeddings import (
-        Embedding,
-        EmbeddingResponse,
-        EmbeddingUsage,
-        BaseEmbeddingsClient,
-        FastEmbedTextEmbeddingsClient,
-        LiteLlmEmbeddingsClient,
-        create_embeddings,
-        async_create_embeddings,
-    )
-
-
-__all__ = (
-    # hammad.ai.completions
-    "CompletionsClient",
-    "Completion",
-    "CompletionChunk",
-    "CompletionsInputParam",
-    "CompletionsModelName",
-    "CompletionsOutputType",
-    "CompletionStream",
-    "AsyncCompletionStream",
-    "async_create_completion",
-    "create_completion",
-    # hammad.ai.embeddings
-    "Embedding",
-    "EmbeddingResponse",
-    "EmbeddingUsage",
-    "BaseEmbeddingsClient",
-    "FastEmbedTextEmbeddingsClient",
-    "LiteLlmEmbeddingsClient",
-    "create_embeddings",
-    "async_create_embeddings",
-)
-
-
-__getattr__ = _auto_create_getattr_loader(__all__)
-
-
-def __dir__() -> list[str]:
-    return list(__all__)